使用OSS MCP Server将数据管理能力集成到AI应用-对象存储-阿里云

使用 OSS MCP Server 将 OSS 数据管理能力集成到 AI 应用中。

重要

这是一个 Alpha 版本，可能会有重大变更。

工具

OSS MCP Server提供以下工具：

列举存储空间（ListBuckets）

支持参数：

[prefix]：限定返回的存储空间名称必须包含的前缀
[marker]：设定结果从 marker 之后按字母排序的第一个开始返回
[maxKeys]：请求返回的最大存储空间数目，默认值为 100，其可设置的最大值可在 OSS MCP Server 实例中配置
[resourceGroupId]：指定返回的存储空间资源组 ID
[region]：OSS 专用地域标识，如 oss-cn-hangzhou，用于指定请求使用的访问域名

查看存储空间的相关信息（GetBucketInfo）

支持参数：

bucket：存储空间名称
[region]：OSS 专用地域标识，如 oss-cn-hangzhou，用于指定请求使用的访问域名

获取指定存储空间的存储容量、文件以及 Multipart 分片数量（GetBucketStat）

支持参数：

bucket：存储空间名称
[region]：OSS 专用地域标识，如 oss-cn-hangzhou，用于指定请求使用的访问域名

环境要求

Node.js >= 18.20.5

STDIO

通过标准输入/输出方式与 MCP Server 通信。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "alibabacloud-oss": {
      "command": "npx",
      "args": ["-y", "alibabacloud-oss-mcp-server@alpha"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your-access-key-id",
        "OSS_ACCESS_KEY_SECRET": "your-access-key-secret"
      }
    }
  }
}

可选环境变量：

OSS_SECURITY_TOKEN：安全令牌，使用临时身份凭证时需要设置
OSS_REGION：OSS 专用地域标识，如 oss-cn-hangzhou
OSS_ENDPOINT：访问域名

Cherry Studio

类型：标准输入/输出
命令：npx
参数：-y alibabacloud-oss-mcp-server@alpha
环境变量：
- OSS_ACCESS_KEY_ID=your-access-key-id（必需）
- OSS_ACCESS_KEY_SECRET=your-access-key-secret（必需）
- OSS_SECURITY_TOKEN=your-security-token（可选，使用临时身份凭证时需要设置）
- OSS_REGION=oss-cn-hangzhou（可选）
- OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com（可选）

Streamable HTTP

通过 HTTP 协议与 MCP Server 通信。

服务端部署

远程访问说明：OSS MCP Server 仅监听 localhost。远程部署时需通过反向代理进行端口转发，并建议配置 HTTPS 和认证保护。

运行以下命令启动 HTTP 服务：

export OSS_ACCESS_KEY_ID="your-access-key-id"
export OSS_ACCESS_KEY_SECRET="your-access-key-secret"

npx -y -p alibabacloud-oss-mcp-server@alpha -p express alibabacloud-oss-mcp-server --transport=streamable-http --port=18081

可选环境变量：

OSS_SECURITY_TOKEN：安全令牌，使用临时身份凭证时需要设置
OSS_REGION：OSS 专用地域标识，如 oss-cn-hangzhou
OSS_ENDPOINT：访问域名

服务端点：http://localhost:18081/mcp

客户端配置

配置客户端连接到已部署的 HTTP 服务端点。

Cherry Studio

类型：可流式传输的 HTTP
URL：http://localhost:18081/mcp

dify

服务端点 URL：http://localhost:18081/mcp

编程方式使用

如需在代码中直接集成 OSS MCP Server，可以通过编程方式创建和配置服务实例。

安装

npm install alibabacloud-oss-mcp-server@alpha

基础用法

import { OSSMcpServer, OSSMcpServerTransport } from 'alibabacloud-oss-mcp-server/server';

const server = new OSSMcpServer({
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  securityToken: process.env.OSS_SECURITY_TOKEN,
  region: process.env.OSS_REGION,
  endpoint: process.env.OSS_ENDPOINT,
  transportType: OSSMcpServerTransport.STDIO
});

await server.runServer();

配置选项

创建 OSSMcpServer 实例时，可以传入以下配置选项：

OSS 客户端配置

accessKeyId：访问密钥 ID
accessKeySecret：访问密钥
[securityToken]：安全令牌
[refreshCredentials]：更新访问凭证方法，若使用临时身份凭证，建议设置该值及 refreshCredentialsInterval 参数，防止临时身份凭证过期
[refreshCredentialsInterval]：访问凭证有效期，单位：毫秒（ms），默认值为 300000 ms，即 5 分钟
[lastRefreshCredentialsTime]：访问凭证最近更新时间，默认值为初始化客户端实例的时间
[region]：地域 ID 或 OSS 专用地域标识，默认值为 oss-cn-hangzhou，此参数将统一转化为地域 ID 用于签名
[endpoint]：访问域名，默认使用 region 参数生成外网访问域名，设置该值则忽略 internal 参数，若该值携带协议部分，则忽略 secure 参数。若 region 参数设置为地域 ID 或需要使用其他域名访问 OSS，请务必设置此参数
[internal]：是否使用内网访问域名，默认值为 false
[secure]：是否使用 HTTPS 协议访问 OSS，默认值为 true
[cname]：endpoint 参数是否为自定义域名，默认值为 false，若该值配置为 true，请设置 endpoint 参数
[sldEnable]：是否使用二级域名方式访问 OSS，默认值为 false
[signVersion]：签名版本，默认值为 ESignVersion.V4，即签名版本 4
[isRequestPay]：是否使用请求者付费模式，默认值为 false，若该值配置为 true，请求中将携带 x-oss-request-payer 请求头，且取值为 requester
[userAgent]：自定义 User-Agent，该值将作为请求头 User-Agent 中的一部分进行发送
[timeout]：请求超时时间，单位：毫秒（ms），默认值为 60000 ms，即 60 秒
[disabledMD5]：是否不计算 Content-MD5 值，默认值为 false
[proxy]：HTTP 请求配置代理设置
[retryMax]：请求失败最大重试次数，默认值为 0
[requestErrorShouldRetry]：请求失败是否重试判断方法，默认全部重试
[amendTimeSkewed]：修正时间偏差，单位：毫秒（ms），默认值为 0
[customRequestFunction]：自定义请求方法
[customSign]：自定义签名方法，配置此参数后，除 POST 签名外的所有需要计算签名的请求都会通过此方法计算签名

MCP Server 配置

[transportType]：通信类型，默认为标准输入/输出（stdio）
[port]：HTTP 服务器监听端口，仅在使用 Streamable HTTP 通信时有效，默认为 18081
[tools]：要启用的工具列表，默认全部启用
[listToolsMaxKeysMaxValue]：列举类工具 maxKeys 参数可设置的最大值（1-1000），默认为 100
[listToolsDefaultMaxKeys]：列举类工具 maxKeys 参数的默认值，默认等于 listToolsMaxKeysMaxValue
[httpServer]：自定义 HTTP 服务器实例（仅在使用 Streamable HTTP 通信时有效）
[logger]：日志记录器实例
[xmlContentText]：工具请求成功后是否以原始 XML 字符串格式返回结果，默认为 false（即返回 JSON 字符串）
[toolsRequestSuccessCallback]：工具请求成功时的回调函数
[toolsRequestErrorCallback]：工具请求失败时的回调函数