Ibm Cos MCP Server

IBM云对象存储MCP服务器

](https://www.npmjs.com/package/@kirtijha/ibm-cos-mcp-server) ](https://www.npmjs.com/package/@kirtijha/ibm-cos-mcp-server)

用于IBM云对象存储的全面、生产就绪的模型上下文协议（MCP）服务器。该服务器提供了对IBM COS的完整的与S3-兼容的API访问，其中包含37个全面的工具，涵盖了对象存储管理的各个方面。

🔗 链接

• GitHub:
• NPM:

特性

🚀 完成S3 API覆盖范围

• 铲斗操作：使用完整配置创建、列出、删除和管理存储桶
• 对象操作：上传、下载、复制、删除单个和多个对象
• 多部分上传：通过并行上传高效处理大文件
• 生命周期管理：自动化对象转换和过期
• 版本控制：跟踪和管理对象版本
• CORS配置：启用跨源资源共享
• 访问控制：管理存储桶和对象ACL
• 标记：使用键值标签组织资源
• 网站托管：配置静态网站托管
• 加密：使用IBM密钥保护的服务器端加密

🔐 灵活的身份验证

• IAM API密钥：建议用于生产
• HMAC凭据：S3兼容的访问密钥和密钥
• 自动凭证刷新和令牌管理

🌐 网络灵活性

• 互联网接入的公共端点
• VPC/内部网络的专用端点
• 高性能应用程序的直接端点

📊 高级功能

• 全面的错误处理和验证
• 详细的日志记录和调试支持
• 对大型对象的流媒体支持
• 列表操作的自动分页
• 完全TypeScript类型安全
• 双模式：用于编排平台的stdio+HTTP

📦 安装

使用npx（推荐-无需安装）

使用服务器的最简单方法是 npx:

{
  "mcpServers": {
    "ibm-cos": {
      "command": "npx",
      "args": ["-y", "@kirtijha/ibm-cos-mcp-server"],
      "env": {
        "IBM_COS_API_KEY": "your-api-key",
        "IBM_COS_SERVICE_INSTANCE_ID": "your-instance-id",
        "IBM_COS_ENDPOINT": "s3.us-south.cloud-object-storage.appdomain.cloud",
        "IBM_COS_REGION": "us-south"
      }
    }
  }
}

全球安装

npm install -g @kirtijha/ibm-cos-mcp-server

然后配置：

{
  "mcpServers": {
    "ibm-cos": {
      "command": "ibm-cos-mcp-server",
      "env": {
        "IBM_COS_API_KEY": "your-api-key",
        "IBM_COS_SERVICE_INSTANCE_ID": "your-instance-id",
        "IBM_COS_ENDPOINT": "s3.us-south.cloud-object-storage.appdomain.cloud",
        "IBM_COS_REGION": "us-south"
      }
    }
  }
}

HTTP服务器模式

作为独立的HTTP服务器运行，用于远程访问或编排平台：

# Set environment variables
export IBM_COS_API_KEY="your-api-key"
export IBM_COS_SERVICE_INSTANCE_ID="your-instance-id"
export IBM_COS_ENDPOINT="s3.us-south.cloud-object-storage.appdomain.cloud"
export IBM_COS_REGION="us-south"
export MCP_API_KEY="your-secure-api-key"
export PORT=3000

# Using npx
npx -y @kirtijha/ibm-cos-mcp-server --http

# Or if installed globally
ibm-cos-mcp-http

服务器将在以下位置可用：

• MCP端点: http://localhost:3000/mcp
• 工具列表: http://localhost:3000/tools
• 健康检查: http://localhost:3000/health

地方发展

为了促进或地方发展：

# Clone the repository
git clone https://github.ibm.com/kirtijha/ibm-cos-mcp-server.git
cd ibm-cos-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

🔑 获取您的凭据

1. 服务实例ID：在IBM Cloud Console中的COS实例详细信息中找到
2. IAM API密钥：在IBM云控制台中创建→ 管理→ 访问（IAM）→ API密钥
3. HMAC凭据 （可选）：在COS实例中创建→ 服务凭据→ 新凭据（启用HMAC）

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required: Service Instance ID
IBM_COS_SERVICE_INSTANCE_ID=your-service-instance-id

# Authentication Option 1: IAM API Key (Recommended)
IBM_COS_API_KEY=your-ibm-cloud-api-key

# Authentication Option 2: HMAC Credentials
# IBM_COS_ACCESS_KEY_ID=your-access-key-id
# IBM_COS_SECRET_ACCESS_KEY=your-secret-access-key

# Endpoint Configuration
IBM_COS_ENDPOINT=s3.us-south.cloud-object-storage.appdomain.cloud
IBM_COS_REGION=us-south

用法

作为MCP服务器（带克劳德桌面）

添加到您的Claude Desktop配置中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ibm-cos": {
      "command": "node",
      "args": ["/path/to/ibm-cos-mcp-server/dist/index.js"],
      "env": {
        "IBM_COS_API_KEY": "your-api-key",
        "IBM_COS_SERVICE_INSTANCE_ID": "your-instance-id",
        "IBM_COS_ENDPOINT": "s3.us-south.cloud-object-storage.appdomain.cloud",
        "IBM_COS_REGION": "us-south"
      }
    }
  }
}

作为HTTP服务器

# Start the HTTP server
npm run start:http
# or
ibm-cos-http-server

服务器将在以下时间可用 http://localhost:3000 （或您配置的端口）。

可用工具

水桶管理（7个工具）

1. list_buckets -列出服务实例中的所有bucket
2. create_bucket -创建一个具有存储类和位置的新存储桶
3. delete_bucket -删除空桶
4. 头巾 -检查bucket是否存在并获取元数据
5. get_bucket_location -获取bucket的位置约束
6. get_bucket_versioning -检查版本控制状态
7. put_bucket_versioning -启用/暂停版本控制

对象操作（11个工具）

1. list_objects -列出bucket中的对象（v1）
2. list_objects_v2 -列出带有延续标记的对象（v2）
3. 输出对象 -上传一个对象
4. get_object -下载对象
5. head对象 -获取对象元数据
6. 删除对象 -删除单个对象
7. 删除对象 -在一个请求中删除多个对象
8. 复制对象 -在bucket之间复制对象
9. get_object_tagging -获取对象标签
10. put_object_tagging -设置对象标签
11. 删除对象标记 -删除对象标记

多部分上传（6个工具）

1. create_multipart_upload -启动多部分上传
2. upload_part -上传零件
3. 完成_多部分_绘图 -完成上传
4. abort_multipart_upload -取消上传
5. list_multipart_uploads -列出活动上传
6. 列表_零件 -列出上传的零件

访问控制（4个工具）

1. get_bucket_acl -获取bucket ACL
2. put_bucket_all -设置bucket ACL
3. get_object_acl -获取对象ACL
4. put_object_acl -设置对象ACL
5. get_public_access_block -获取公共访问设置
6. put_public_access_block -配置公共访问

高级功能（6个工具）

1. get_bucket_cors -获取CORS配置
2. put_bucket_cors -设置CORS规则
3. delete_bucket_cors -删除CORS配置
4. get_bucket_web -获取网站配置
5. put_bucket_web -配置静态网站
6. delete_bucket_wwwite -删除网站配置

复制和保护（4个工具）

1. get_bucketreplication -获取复制配置
2. put_bucketreplication -配置复制
3. delete_bucketreplication -删除复制
4. get_bucket_保护 -获取不可变对象存储配置

例子

上传文件

// The MCP server handles this automatically when you use:
// "Upload file.txt to my-bucket in IBM COS"

使用生命周期规则创建Bucket

// 1. Create the bucket first
// "Create a bucket named 'archive-bucket' in us-south"

// 2. Then configure lifecycle rules
// "Set lifecycle rules for 'archive-bucket' to expire objects after 90 days"

为Web应用程序配置CORS

// "Configure CORS for 'my-app-bucket' to allow requests from https://myapp.com"

下载和处理对象

// "List all PDF files in 'documents' bucket and download the latest one"

按区域划分的端点

美国地区

• s3.us-south.cloud-object-storage.appdomain.cloud （达拉斯）
• s3.us-east.cloud-object-storage.appdomain.cloud （华盛顿特区）

欧盟地区

• s3.eu-de.cloud-object-storage.appdomain.cloud （法兰克福）
• s3.eu-gb.cloud-object-storage.appdomain.cloud （伦敦）

AP地区

• s3.ap-south.cloud-object-storage.appdomain.cloud （东京）
• s3.ap-north.cloud-object-storage.appdomain.cloud （首尔）

对于私有端点，请替换 s3 随着 s3.private.\ 对于直接端点，请替换 s3 随着 s3.direct.

建筑

ibm-cos-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server entry
│   ├── http-server.ts        # HTTP server entry
│   ├── server/
│   │   ├── http-server-base.ts
│   │   └── ibm-cos-http.ts
│   ├── tools/               # 37 tool implementations
│   │   ├── listBuckets.ts
│   │   ├── createBucket.ts
│   │   ├── putObject.ts
│   │   ├── getObject.ts
│   │   ├── ... (33 more tools)
│   ├── types/               # TypeScript type definitions
│   └── utils/               # Shared utilities
└── dist/                    # Compiled JavaScript

错误处理

服务器提供详细的错误消息和处理：

• 身份验证失败
• 无效凭证
• 找不到桶/对象
• 权限不足
• 网络错误
• 请求格式错误

安全最佳实践

1. 从不提交凭据 -使用环境变量
2. 使用IAM API密钥 -建议使用HMAC凭据
3. 启用版本控制 -防止意外删除
4. 配置生命周期规则 -自动管理存储成本
5. 使用私有端点 -用于内部应用程序
6. 启用加密 -对敏感数据使用IBM密钥保护
7. 实现最小特权 -授予所需的最低权限

性能提示

1. 使用多部分上传 -对于大于100MB的文件
2. 启用并行上传 -同时上传零件
3. 使用直接端点 -适用于高通量应用
4. 实现重试逻辑 -处理瞬态故障
5. 缓存桶位置 -减少API调用
6. 使用流媒体 -用于大型对象下载

故障排除

连接问题

• 验证您所在地区的端点是否正确
• 检查网络连接
• 确保防火墙允许HTTPS流量

身份验证错误

• 验证API密钥是否有效且未过期
• 检查服务实例ID是否正确
• 确保凭据具有所需的权限

权限不足

• 验证IAM策略是否授予所需的访问权限
• 检查存储桶策略和ACL
• 确保服务实例可访问

发展

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes
npm run watch

# Start HTTP server in dev mode
npm run dev:http

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• GitHub问题： 报告错误
• IBM云文档： 对象存储文档
• API参考： S3 API兼容性

致谢

内置：

• 模型上下文协议SDK
• IBM COS SDK
• TypeScript和Node.js

______________________________________________________________________

由以下材料制成❤️ IBM Cloud社区