阿里云OSS MCP服务器

🚀 为阿里云OSS (Object Storage Service) 提供的MCP (Model Context Protocol) 服务器，支持完整的云存储操作功能。

✨ 特性

🔌 完整的OSS功能: 支持文件上传、下载、删除、列表等全部操作
📡 MCP协议支持: 基于stdio协议，与AI助手无缝集成
⚡ 高性能: 支持分片上传、并发操作和智能缓存
🔧 易于配置: 环境变量配置，支持配置热重载
🛡️ 安全可靠: 完善的错误处理、访问控制和审计日志
🔍 可观测性: 健康检查、性能监控和结构化日志
🧩 可扩展: 插件系统和中间件架构
📦 开箱即用: 支持npx一键运行

🚀 快速开始

1. 安装

# 全局安装
npm install -g aigroup-aliyunoss-mcp

# 或者使用 npx 临时运行
npx aigroup-aliyunoss-mcp --help

2. 配置OSS凭据

创建 .env 文件或设置环境变量：

# 阿里云OSS配置
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret  
OSS_BUCKET=your_bucket_name
OSS_REGION=oss-cn-beijing

# 可选配置
OSS_SECURE=true
OSS_TIMEOUT=300
FILE_EXPIRY_HOURS=1

3. 添加到MCP配置

编辑MCP设置文件 (如 Claude Desktop):

{
  "mcpServers": {
    "aigroup-aliyunoss-mcp": {
      "command": "npx",
      "args": ["aigroup-aliyunoss-mcp", "--stdio"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your_access_key_id",
        "OSS_ACCESS_KEY_SECRET": "your_access_key_secret",
        "OSS_BUCKET": "your_bucket_name", 
        "OSS_REGION": "oss-cn-beijing"
      }
    }
  }
}

4. 验证安装

# 健康检查
npx aigroup-aliyunoss-mcp --health

# 查看帮助
npx aigroup-aliyunoss-mcp --help

# 验证配置
npx aigroup-aliyunoss-mcp --validate-config

🔧 配置详解

环境变量

| 变量名 | 必需 | 默认值 | 说明 | |--------|------|--------|------| | OSS_ACCESS_KEY_ID | ✅ | - | 阿里云访问密钥ID | | OSS_ACCESS_KEY_SECRET | ✅ | - | 阿里云访问密钥Secret | | OSS_BUCKET | ✅ | - | OSS存储桶名称 | | OSS_REGION | ✅ | - | OSS地域 (如: oss-cn-beijing) | | OSS_SECURE | ❌ | true | 是否使用HTTPS | | OSS_TIMEOUT | ❌ | 300 | 请求超时时间(秒) | | FILE_EXPIRY_HOURS | ❌ | 1 | 临时链接有效期(小时) | | MCP_LOG_LEVEL | ❌ | info | 日志级别 (debug/info/warn/error) | | MCP_MAX_FILE_SIZE | ❌ | 100 | 最大文件大小(MB) | | MULTIPART_THRESHOLD | ❌ | 10 | 分片上传阈值(MB) |

获取阿里云OSS凭据

登录阿里云控制台
创建或选择一个OSS存储桶
在 RAM访问控制中创建用户
为用户分配OSS相关权限
生成访问密钥对

📋 可用工具

| 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | uploadFile | 上传文件到OSS | fileName, file, contentType | | downloadFile | 从OSS下载文件 | fileName, localPath | | deleteObject | 删除OSS文件 | fileName | | deleteMultipleObjects | 批量删除文件 | fileNames[] | | listObjects | 列出OSS文件 | prefix, maxKeys, marker | | getObjectUrl | 生成临时访问链接 | fileName, expires | | copyObject | 复制OSS文件 | source, target | | getObjectMeta | 获取文件元数据 | fileName | | putObjectACL | 设置文件权限 | fileName, acl | | getObjectACL | 获取文件权限 | fileName | | multipartUpload | 分片上传大文件 | fileName, filePath, partSize | | initMultipartUpload | 初始化分片上传 | fileName | | uploadPart | 上传文件分片 | fileName, uploadId, partNo, data | | completeMultipartUpload | 完成分片上传 | fileName, uploadId, parts | | abortMultipartUpload | 取消分片上传 | fileName, uploadId | | listUploads | 列出进行中的分片上传 | prefix, maxUploads |

💡 使用示例

基础文件操作

// 上传文件
{
  "tool": "uploadFile",
  "arguments": {
    "fileName": "documents/report.pdf",
    "file": "/local/path/to/report.pdf",
    "contentType": "application/pdf"
  }
}

// 生成临时下载链接
{
  "tool": "getObjectUrl", 
  "arguments": {
    "fileName": "documents/report.pdf",
    "expires": 3600
  }
}

// 列出文件
{
  "tool": "listObjects",
  "arguments": {
    "prefix": "documents/",
    "maxKeys": 50
  }
}

批量操作

// 批量删除文件
{
  "tool": "deleteMultipleObjects",
  "arguments": {
    "fileNames": [
      "temp/file1.txt",
      "temp/file2.txt", 
      "temp/file3.txt"
    ]
  }
}

分片上传大文件

// 自动分片上传
{
  "tool": "multipartUpload",
  "arguments": {
    "fileName": "videos/large-video.mp4",
    "filePath": "/local/path/to/large-video.mp4",
    "partSize": 5242880
  }
}

🔍 监控和诊断

健康检查

# 完整健康检查
npx aigroup-aliyunoss-mcp --health

# JSON格式输出
npx aigroup-aliyunoss-mcp --health --json

健康检查包括：

✅ 配置验证
✅ OSS连接测试
✅ 内存使用监控
✅ 依赖服务状态

日志记录

服务支持结构化JSON日志，输出到stderr：

{
  "timestamp": "2025-08-18T12:00:00.000Z",
  "level": "info",
  "component": "UploadTool", 
  "message": "文件上传成功",
  "fileName": "test.jpg",
  "size": 102400,
  "duration": 1250,
  "traceId": "abc123def456"
}

性能监控

响应时间: 每个工具调用的耗时统计
吞吐量: 文件传输速率监控
错误率: 操作失败率统计
资源使用: 内存和CPU使用率

🛠️ 开发和自定义

本地开发

# 克隆项目
git clone https://github.com/your-org/aigroup-aliyunoss-mcp.git
cd aigroup-aliyunoss-mcp

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 编辑 .env 文件

# 开发模式运行
npm run dev

插件开发

创建自定义插件扩展功能：

// plugins/my-plugin/index.ts
import { Plugin, PluginContext } from 'aigroup-aliyunoss-mcp';

export default class MyPlugin implements Plugin {
  metadata = {
    name: 'my-plugin',
    version: '1.0.0',
    description: '自定义插件',
    author: 'Your Name'
  };

  async onLoad(context: PluginContext) {
    context.logger.info('插件加载成功');
  }

  getTools() {
    return [{
      name: 'myCustomTool',
      description: '自定义工具',
      inputSchema: { /* zod schema */ },
      handler: async (args, context) => {
        // 工具逻辑
        return { success: true };
      }
    }];
  }
}

中间件开发

// 自定义中间件
const customMiddleware: MiddlewareDefinition = {
  name: 'custom-middleware',
  priority: 500,
  handler: async (context, next) => {
    // 前置处理
    console.log(`调用工具: ${context.toolName}`);
    
    await next();
    
    // 后置处理
    console.log(`工具执行完成`);
  }
};

🐛 故障排除

常见问题

1. OSS连接失败

错误: OSS_CONNECTION_ERROR

解决方案:

检查网络连接
验证OSS凭据是否正确
确认存储桶名称和地域设置
检查防火墙和代理设置

2. 权限不足

错误: OSS_PERMISSION_ERROR

解决方案:

检查RAM用户权限设置
确认存储桶访问权限
验证访问密钥是否有效

3. 文件上传失败

错误: FILE_UPLOAD_FAILED

解决方案:

检查文件路径是否正确
验证文件大小是否超出限制
检查文件类型是否被允许
增加超时时间配置

4. 配置无效

错误: CONFIG_INVALID

解决方案:

运行 npx aigroup-aliyunoss-mcp --validate-config
检查必需的环境变量
验证配置文件格式

调试模式

# 启用调试日志
MCP_LOG_LEVEL=debug npx aigroup-aliyunoss-mcp --stdio

# 查看详细错误信息
npx aigroup-aliyunoss-mcp --health --verbose

获取支持

🤝 贡献

欢迎贡献代码！请阅读贡献指南了解详情。

开发工作流

Fork 项目仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'feat: 添加新功能')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

代码规范

使用 TypeScript 严格模式
遵循 ESLint 和 Prettier 规则
编写单元测试覆盖新功能
更新相关文档

📄 许可证

本项目使用 MIT 许可证。

🙏 致谢

Model Context Protocol - MCP协议规范
阿里云OSS - 对象存储服务
ali-oss - 阿里云OSS SDK

Made with ❤️ by the aigroup-aliyunoss-mcp team

MCP Servers

阿里云OSS MCP服务器

✨ 特性

🚀 快速开始

1. 安装

2. 配置OSS凭据

3. 添加到MCP配置

4. 验证安装

🔧 配置详解

环境变量

获取阿里云OSS凭据

📋 可用工具

💡 使用示例

基础文件操作

批量操作

分片上传大文件

🔍 监控和诊断

健康检查

日志记录

性能监控

🛠️ 开发和自定义

本地开发

插件开发

中间件开发

🐛 故障排除

常见问题

1. OSS连接失败

2. 权限不足

3. 文件上传失败

4. 配置无效

调试模式

获取支持

🤝 贡献

开发工作流

代码规范

📄 许可证

🙏 致谢

安装包（如果需要）

Cursor 配置 (mcp.json)

Aigroup Stata MCP

阿里云OSS MCP服务器

✨ 特性

🚀 快速开始

1. 安装

2. 配置OSS凭据

3. 添加到MCP配置

4. 验证安装

🔧 配置详解

环境变量

获取阿里云OSS凭据

📋 可用工具

💡 使用示例

基础文件操作

批量操作

分片上传大文件

🔍 监控和诊断

健康检查

日志记录

性能监控

🛠️ 开发和自定义

本地开发

插件开发

中间件开发

🐛 故障排除

常见问题

1. OSS连接失败

2. 权限不足

3. 文件上传失败

4. 配置无效

调试模式

获取支持

🤝 贡献

开发工作流

代码规范

📄 许可证

🙏 致谢

安装包 （如果需要）

Cursor 配置 (mcp.json)

Aigroup Stata MCP

安装包（如果需要）