对象存储（OSS）MCP Server（Alpha）

基于 Model Context Protocol（MCP）的阿里云对象存储（OSS）MCP Server，帮助开发者快速将 OSS 数据管理能力集成到 AI 应用中。

⚠️ 注意：这是一个 Alpha 版本，可能会有重大变更。

环境要求

Node.js >= 18.20.5

安装

npm install alibabacloud-oss-mcp-server@alpha

或

npm install [email protected]

可选依赖

如使用Streamable HTTP 通信方式，直接在 AI 客户端中或通过编程方式但未设置httpServer选项时使用，则需要额外安装 Express：

npm install express

功能特性

提供以下 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，用于指定请求使用的访问域名

使用方式

在 AI 客户端中使用（以 Cherry Studio 为例）

准备工作

1. 安装 Cherry Studio，进入设置界面
2. 点击 “MCP” 选项，根据提示安装 MCP 环境依赖
3. 配置以下环境变量：
   • OSS_ACCESS_KEY_ID：访问密钥 ID
   • OSS_ACCESS_KEY_SECRET：访问密钥
   • OSS_SECURITY_TOKEN：（可选）安全令牌，使用临时身份凭证时需要设置
   • OSS_REGION：（可选）OSS 专用地域标识，如 oss-cn-hangzhou
   • OSS_ENDPOINT：（可选）访问域名

方法一：使用标准输入/输出（stdio）通信

1. 点击“添加”，设置名称、描述等选项，类型选项选择“标准输入/输出”
2. 命令选项填写node
3. 参数选项填写工具的安装路径，如/Users/test/yourProject/node_modules/alibabacloud-oss-mcp-server/dist/index.js
4. 保存配置并启用服务

方法二：使用 Streamable HTTP 通信

1. 在您的项目目录下，通过命令行启动本地服务，如：

   npx alibabacloud-oss-mcp-server --transport=streamable-http --port=18081

   或

   node ./node_modules/alibabacloud-oss-mcp-server --transport=streamable-http --port=18081

   支持指定以下参数：

   • --transport=streamable-http：指定通信类型为 Streamable HTTP
   • --port=<number>：（可选）指定监听端口，默认为 18081

2. 进入 Cherry Studio 设置页面，点击 “MCP” 选项

3. 点击“添加”，设置名称、描述等选项，类型选项选择“可流式传输的 HTTP”

4. URL 选项填写本地服务启动的 URL，如http://localhost:18081/mcp

5. 保存配置并启用服务

编程方式使用

基础用法

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
});

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

许可证

MIT