Skip to main content
Glama
lvchenyang

alioss-mcp-server

by lvchenyang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

阿里云OSS图片转存MCP服务器

一个基于Model Context Protocol (MCP)的服务器，支持两种模式将图片URL转存到阿里云OSS并返回CDN访问地址。

架构特点: 支持OSS直传和HOOK代理两种模式，使用STS临时凭证确保安全，提供完整的图片上传和管理功能。

MCP工具说明

transfer_image_to_oss

将指定URL的图片转存到阿里云OSS，并返回新的CDN访问地址。

参数：

  • imageURL (string): 要转存的图片URL地址

返回结果：

{
  "structuredContent": {
    "success": true,
    "data": {
      "cdnUrl": "https://cdn.example.com/images/photo_123.jpg",
      "fileName": "images/photo_123.jpg", 
      "originalUrl": "https://source.example.com/photo.jpg"
    },
    "message": "Image successfully transferred to OSS"
  },
  "content": [{
    "type": "text",
    "text": "{\"success\":true,\"data\":{\"cdnUrl\":\"https://cdn.example.com/images/photo_123.jpg\",\"fileName\":\"images/photo_123.jpg\",\"originalUrl\":\"https://source.example.com/photo.jpg\"},\"message\":\"Image successfully transferred to OSS\"}"
  }]
}

错误返回格式：

{
  "isError": true,
  "structuredContent": {
    "success": false,
    "data": null,
    "error": "Invalid URL format",
    "message": "Failed to transfer image to OSS"
  },
  "content": [{
    "type": "text",
    "text": "Error: Invalid URL format"
  }]
}

功能特性：

  • 🔄 双模式支持: OSS直传和HOOK代理两种模式

  • 🔑 STS安全: OSS模式使用STS临时凭证，确保最小权限原则

  • 🌐 支持HTTP/HTTPS协议的图片URL

  • ⚡ OSS模式：直接SDK集成，高性能上传

  • 🔗 HOOK模式：API代理上传，兼容现有系统

  • 🔒 完整的安全验证和文件类型检查

  • 📏 文件大小限制（最大50MB）

  • 🏷️ 智能文件名处理，防止路径遍历攻击

  • 📋 MCP规范: 完整符合官方规范，包含outputSchema定义

  • 🎯 结构化数据: 提供structuredContent字段，直接访问结构化数据

  • 🔄 向后兼容: 同时提供content数组，支持传统客户端

  • ⚡ 错误处理: 规范的isError标记和错误详情

  • 🩺 健康检查: 内置配置验证和状态监控

Related MCP server: ImgBB MCP Server

环境变量配置

项目支持两种上传模式：OSS模式（直接上传到阿里云OSS）和 HOOK模式（通过API接口上传）。

基础配置

# MCP服务端口
PORT=3004

# 上传模式 (OSS 或 HOOK)
UPLOAD_MODE=OSS

OSS模式配置

当 UPLOAD_MODE=OSS 时，需要配置以下环境变量：

# STS临时凭证配置
STS_ACCESS_KEY_ID=your_sts_access_key_id
STS_ACCESS_KEY_SECRET=your_sts_access_key_secret
STS_ROLE_ARN=acs:ram::your_account_id:role/your_role_name
STS_ENDPOINT=sts.cn-hangzhou.aliyuncs.com

# OSS存储配置
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_BUCKET=your_bucket_name

# CDN配置
CDN_ENDPOINT=https://your-cdn-domain.com

OSS模式说明:

  • 使用STS临时凭证，提供最小权限原则，更加安全

  • 直接通过阿里云OSS SDK上传，性能更好

  • 确保RAM角色具有对应OSS存储桶的PutObject和GetObject权限

HOOK模式配置

当 UPLOAD_MODE=HOOK 时，需要配置以下环境变量：

# HOOK上传接口URL
UPLOAD_HOOK_URL=http://your-api-server:3001/api/resources/transfer-image-to-oss

HOOK模式说明:

  • 通过API接口代理上传，适合集成现有系统

  • 支持多种响应格式自动适配

  • 无需配置OSS相关参数，由后端API处理

MCP客户端集成

本MCP服务器支持两种通信模式：

  • stdio模式：适用于Cursor等桌面MCP客户端，通过命令行直接启动

  • HTTP模式：适用于Docker部署和N8N等服务器环境

配置示例

OSS模式配置：

{
  "mcpServers": {
    "alioss-mcp-server": {
      "command": "npx",
      "args": ["-y","alioss-mcp-server@latest"],
      "env": {
        "UPLOAD_MODE": "OSS",
        "STS_ACCESS_KEY_ID": "your_sts_access_key_id",
        "STS_ACCESS_KEY_SECRET": "your_sts_access_key_secret",
        "STS_ROLE_ARN": "acs:ram::your_account_id:role/your_role_name",
        "OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com",
        "OSS_BUCKET": "your_bucket_name",
        "CDN_ENDPOINT": "https://your-cdn-domain.com"
      }
    }
  }
}

HOOK模式配置：

{
  "mcpServers": {
    "alioss-mcp-server": {
      "command": "npx",
      "args": ["-y","alioss-mcp-server@latest"],
      "env": {
        "UPLOAD_MODE": "HOOK",
        "UPLOAD_HOOK_URL": "http://your-api-server:3001/api/resources/transfer-image-to-oss"
      }
    }
  }
}

🔧 自动模式检测：

  • 默认使用stdio模式，适合所有MCP客户端（Cursor、Claude Desktop等）

  • 当设置PORT环境变量或使用--http参数时，自动切换到HTTP模式（适合Docker部署）

  • 可通过MCP_TRANSPORT=http环境变量强制指定HTTP模式

Docker部署

方式一：使用 Docker Compose（推荐）

  1. 创建环境变量文件

复制配置模板：

cp env.example .env

编辑 .env 文件，根据选择的模式填写配置：

# OSS模式配置示例
UPLOAD_MODE=OSS
STS_ACCESS_KEY_ID=your_sts_access_key_id
STS_ACCESS_KEY_SECRET=your_sts_access_key_secret
STS_ROLE_ARN=acs:ram::your_account_id:role/your_role_name
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_BUCKET=your_bucket_name
CDN_ENDPOINT=https://your-cdn-domain.com

# 或者 HOOK模式配置示例
# UPLOAD_MODE=HOOK
# UPLOAD_HOOK_URL=http://your-api-server:3001/api/resources/transfer-image-to-oss

  1. 启动服务

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f alioss-mcp-server

# 停止服务
docker-compose down

方式二：直接使用 Docker

OSS模式：

docker build -t alioss-mcp-server .

docker run -d \
  --name alioss-mcp-server \
  -p 3004:3004 \
  -e UPLOAD_MODE=OSS \
  -e STS_ACCESS_KEY_ID=your_sts_access_key_id \
  -e STS_ACCESS_KEY_SECRET=your_sts_access_key_secret \
  -e STS_ROLE_ARN=your_role_arn \
  -e OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com \
  -e OSS_BUCKET=your_bucket_name \
  -e CDN_ENDPOINT=https://your-cdn-domain.com \
  alioss-mcp-server

HOOK模式：

docker run -d \
  --name alioss-mcp-server \
  -p 3004:3004 \
  -e UPLOAD_MODE=HOOK \
  -e UPLOAD_HOOK_URL=http://your-api-server:3001/api/resources/transfer-image-to-oss \
  alioss-mcp-server

访问Docker部署的MCP服务

服务端点

Docker容器启动后，MCP服务将在以下端点可用：

  • MCP端点: http://localhost:3004/messages

  • 健康检查: http://localhost:3004/health

验证服务状态

# 检查容器状态
docker ps | grep alioss-mcp-server

# 查看服务日志
docker logs alioss-mcp-server

# 健康检查
curl http://localhost:3004/health

MCP客户端连接Docker服务

{
  "mcpServers": {
    "alioss-mcp-server": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "http://localhost:3004/messages",
        "-H", "Content-Type: application/json",
        "--data-raw"
      ]
    }
  }
}

本地开发

# 安装依赖
pnpm install

# 开发模式启动
pnpm dev

# 构建
pnpm build

# 生产模式启动
pnpm start

N8N集成

Docker服务启动后，可以在N8N中使用：

前置要求

  • 安装 n8n-nodes-mcp 社区节点

  • 设置环境变量：N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

配置MCP Client节点

  • Connection Type: HTTP Streamable

  • HTTP Streamable URL: http://localhost:3004/messages（本地Docker）或 http://your-server-ip:3004/messages（远程Docker）

  • Authentication: None

使用transfer_image_to_oss工具

在N8N工作流中添加MCP Client节点，执行工具时传入：

{
  "imageURL": "https://example.com/image.jpg"
}

技术架构

本MCP服务器支持两种架构模式：

OSS模式架构

Claude/Cursor → MCP Server → 阿里云OSS
              (端口3004)     (直接SDK调用)
                  ↓
             STS临时凭证服务

HOOK模式架构

Claude/Cursor → MCP Server → API Server → 阿里云OSS
              (端口3004)     (HOOK URL)

技术栈

  • 架构模式: 双模式支持 (OSS直传 + HOOK代理)

  • 传输协议: HTTP Streamable (MCP 推荐标准)

  • Web框架: Express.js (轻量级)

  • OSS SDK: ali-oss (官方SDK，OSS模式)

  • 安全认证: 阿里云STS + RAM角色 (OSS模式)

  • MCP协议: 原生支持 (无额外依赖)

  • 容器化: Docker + Docker Compose

架构优势

OSS模式:

  • ✅ 安全性高: STS临时凭证 + 最小权限原则

  • ✅ 性能优异: 直接SDK调用，减少网络开销

  • ✅ 独立部署: 无需依赖外部API服务

HOOK模式:

  • ✅ 兼容性好: 可集成现有API系统

  • ✅ 灵活部署: 适应不同的基础设施

  • ✅ 集中管理: 复用现有的上传逻辑

通用优势:

  • ✅ 模式切换: 配置简单，一键切换

  • ✅ 易于维护: 代码集中，逻辑清晰

  • ✅ 容器友好: 完整的Docker支持

端点说明

  • POST /messages: HTTP Streamable MCP端点，支持所有MCP操作

  • GET /health: 健康检查端点

使用示例

在 Claude Desktop 中使用

配置完成后，您可以在对话中直接使用：

请帮我将这个图片转存到OSS：https://example.com/image.jpg

Claude 会自动调用 MCP 服务将图片上传到阿里云OSS并返回CDN地址。

在 Cursor 中使用

在代码编辑器中，您可以通过AI助手上传图片：

@alioss-mcp-server 请将这个截图上传到OSS: https://screenshot.example.com/img.png

故障排除

常见问题

  1. 服务启动失败

    • 检查环境变量配置是否正确

    • 确认网络连接正常

    • 查看服务日志获取详细错误信息

  2. 上传失败

    • OSS模式：检查STS凭证和权限配置

    • HOOK模式：确认API接口可访问

    • 检查图片URL是否有效

  3. MCP客户端连接失败

    • 确认服务正在运行（端口3004）

    • 检查客户端配置文件格式

    • 重启MCP客户端

  4. 权限问题

    • 确保RAM角色具有OSS权限

    • 检查STS配置是否正确

    • 验证OSS存储桶访问权限

  5. 网络问题

    • 检查防火墙设置

    • 确认OSS endpoint可访问

    • 验证代理设置

健康检查

访问健康检查端点查看服务状态：

curl http://localhost:3004/health

返回示例：

{
  "status": "ok",
  "service": "alioss-mcp-server",
  "initialized": true,
  "tools": 1,
  "uploadMode": "OSS",
  "configured": true
}

状态说明：

  • status: 服务状态 (ok 或 warning)

  • service: 服务名称

  • initialized: MCP服务器是否已初始化

  • tools: 可用工具数量

  • uploadMode: 当前上传模式

  • configured: 配置是否完整

  • missingConfig: 缺失的配置项（如果有）

获取帮助

如果您有任何问题：

  • 查看项目文档和 env.example 配置模板

  • 检查健康检查端点获取服务状态

  • 搜索现有的 issues

  • 创建新的 issue 提问

安全问题报告

如发现安全问题，请通过 GitHub Issues 报告，并在标题中标注 [SECURITY]。

许可证

本项目基于 MIT 许可证 开源。

贡献

欢迎贡献代码、报告问题或提出建议！请查看 CONTRIBUTING.md 了解详细信息。

感谢您的关注和支持！

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers