阿里云OSS MCP 服务器

March 18, 2025 · View on GitHub

为 Cursor、Windsurf、Cline 和其他AI编码工具提供阿里云OSS访问能力的 Model Context Protocol 服务器。

通过这个MCP服务器，AI编码工具可以直接操作阿里云OSS存储，上传、下载、管理文件，无需手动处理繁琐的存储操作。

快速开始

npx alioss-mcp --accessKeyId=YOUR_KEY --accessKeySecret=YOUR_SECRET --bucket=YOUR_BUCKET --region=YOUR_REGION --workingDirectory=/path/to/your/workspace

安装方式

使用NPM快速运行

你可以不需要安装或构建仓库，直接通过NPM运行服务器：

npx alioss-mcp --accessKeyId=YOUR_KEY --accessKeySecret=YOUR_SECRET --bucket=YOUR_BUCKET --region=YOUR_REGION --workingDirectory=/path/to/your/workspace
# 或者
pnpx alioss-mcp --accessKeyId=YOUR_KEY --accessKeySecret=YOUR_SECRET --bucket=YOUR_BUCKET --region=YOUR_REGION --workingDirectory=/path/to/your/workspace
# 或者
yarn dlx alioss-mcp --accessKeyId=YOUR_KEY --accessKeySecret=YOUR_SECRET --bucket=YOUR_BUCKET --region=YOUR_REGION --workingDirectory=/path/to/your/workspace

注意： workingDirectory 参数是可选的，默认为当前工作目录。它指定了本地操作文件的根目录，如上传和下载文件时的相对路径基准。

对于使用配置文件的工具

许多工具如Windsurf、Cline和Claude Desktop使用配置文件启动服务器。alioss-mcp服务器可以通过在配置文件中添加以下内容来配置：

{
  "mcpServers": {
    "alioss-mcp": {
      "command": "npx",
      "args": ["-y", "alioss-mcp", "--stdio"],
      "env": {
        "OSS_ACCESS_KEY_ID": "YOUR_KEY",
        "OSS_ACCESS_KEY_SECRET": "YOUR_SECRET",
        "OSS_BUCKET": "YOUR_BUCKET",
        "OSS_REGION": "YOUR_REGION",
        "WORKING_DIRECTORY": "/path/to/your/workspace"
      }
    }
  }
}

配置选项

服务器可以使用环境变量（通过.env文件）或命令行参数进行配置。命令行参数优先于环境变量。

环境变量

OSS_ACCESS_KEY_ID: 你的阿里云AccessKeyId（必需）
OSS_ACCESS_KEY_SECRET: 你的阿里云AccessKeySecret（必需）
OSS_BUCKET: 你想要操作的OSS存储桶（必需）
OSS_REGION: OSS区域位置，如oss-cn-beijing（必需）
WORKING_DIRECTORY: 本地工作目录（可选，默认为当前目录）
PORT: 服务器运行的端口（可选，默认为3000）

命令行参数

--version: 显示版本号
--accessKeyId: 你的阿里云AccessKeyId
--accessKeySecret: 你的阿里云AccessKeySecret
--bucket: 你想要操作的OSS存储桶
--region: OSS区域位置
--workingDirectory: 本地工作目录，所有本地文件操作的基准路径
--stdio: 在命令行模式运行服务器，而非默认的HTTP/SSE模式
--help: 显示帮助菜单

与Cursor连接

启动服务器

> npx alioss-mcp --accessKeyId=YOUR_KEY --accessKeySecret=YOUR_SECRET --bucket=YOUR_BUCKET --region=YOUR_REGION --workingDirectory=/path/to/your/workspace
# 初始化阿里云OSS MCP服务器...
# HTTP服务器监听端口3000
# SSE端点可在http://localhost:3000/sse访问
# 消息端点可在http://localhost:3000/messages访问

连接Cursor到MCP服务器

服务器运行后，在Cursor的设置中找到features选项卡，连接Cursor到MCP服务器。

可用工具

服务器提供以下MCP工具：

基本对象操作

uploadFile: 上传文件到OSS
downloadFile: 从OSS下载文件
listObjects: 列出OSS中的文件
deleteObject: 删除OSS中的文件
getObjectUrl: 获取OSS文件的签名URL
copyObject: 在OSS中复制文件
getObjectMeta: 获取OSS文件的元数据

批量和访问控制操作

deleteMultipleObjects: 批量删除多个OSS文件
putObjectACL: 设置OSS文件的访问权限
getObjectACL: 获取OSS文件的访问权限

分片上传功能

multipartUpload: 一步完成分片上传（自动处理分片）
initMultipartUpload: 初始化分片上传任务
uploadPart: 上传文件分片
completeMultipartUpload: 完成分片上传
abortMultipartUpload: 取消分片上传
listUploads: 列出未完成的分片上传任务

示例用法

上传文件

上传一个本地文件到OSS

uploadFile(ossPath: "example/test.jpg", localPath: "local/path/to/image.jpg")

注意：文件路径 local/path/to/image.jpg 是相对于 workingDirectory 的路径。

下载文件

从OSS下载文件到本地

downloadFile(ossPath: "example/test.jpg", localPath: "local/download/image.jpg")

注意：文件路径 local/download/image.jpg 是相对于 workingDirectory 的路径。

列出文件

列出OSS存储桶中的文件

listObjects(prefix: "example/", maxKeys: 50)

使用分片上传大文件

初始化分片上传
const initResult = initMultipartUpload(objectName: "large-file.zip")

上传各个分片
const part1 = uploadPart(objectName: "large-file.zip", uploadId: initResult.uploadId, partNumber: 1, 
                         localPath: "local/large-file.zip", start: 0, end: 5242880)
const part2 = uploadPart(objectName: "large-file.zip", uploadId: initResult.uploadId, partNumber: 2, 
                         localPath: "local/large-file.zip", start: 5242880, end: 10485760)

完成分片上传
completeMultipartUpload(objectName: "large-file.zip", uploadId: initResult.uploadId, parts: [part1, part2])

注意：文件路径 local/large-file.zip 是相对于 workingDirectory 的路径。

一步完成分片上传

使用自动分片上传大文件

multipartUpload(objectName: "large-file.zip", localPath: "local/large-file.zip", partSize: 2097152)

注意：文件路径 local/large-file.zip 是相对于 workingDirectory 的路径。

贡献

欢迎通过GitHub Issues和Pull Requests进行贡献。

许可证

MIT