ivy-img-upload-mcp

v1.1.1

Published

3 months ago

MCP 图片上传服务，支持 Base64 格式上传到七牛云

Downloads

0High
0Medium
0Low

morecode

mcp upload qiniu image

Ivy Upload MCP 服务

一个基于 MCP (Model Context Protocol) 的图片上传服务，支持将文件上传到七牛云存储。

功能特性

✅ 支持文件流（FormData）格式上传
✅ 支持 Base64 编码格式上传
✅ 自动处理 Base64 前缀（data:image/...;base64,）
✅ 支持图片压缩（转换为 JPEG 格式）
✅ 自动获取上传凭证，无需手动配置
✅ 返回文件访问 URL、hash 和 key
✅ 可部署到云端，供 Cursor、Claude Desktop 等工具使用
✅ 完整的 TypeScript 支持

安装

本地安装

npm install
npm run build

从 npm 安装

npm install -g ivy-img-upload-mcp

配置

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加：

macOS/Linux: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "ivy-upload": {
      "command": "node",
      "args": ["/Users/tianrui/projects/ivy_upload/dist/index.js"]
    }
  }
}

或者使用 npx 方式：

{
  "mcpServers": {
    "ivy-upload": {
      "command": "npx",
      "args": ["-y", "ivy-img-upload-mcp"]
    }
  }
}

在 Claude Desktop 中配置

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ivy-upload": {
      "command": "node",
      "args": ["/path/to/ivy_upload/dist/index.js"]
    }
  }
}

使用方法

服务提供了两个工具：

1. upload_file - 上传文件

上传本地文件到七牛云：

// 在 AI 助手中使用
// AI 会自动读取文件并上传
upload_file({
  file: "/path/to/image.png",
  timeout: 30000  // 可选，默认 30 秒
})

参数说明：

file (必填): 文件路径
timeout (可选): 上传超时时间（毫秒），默认 30000

返回结果：

{
  "key": "FhGRLUokkOGkZ9WLj6OdZPIjIzqD",
  "hash": "FhGRLUokkOGkZ9WLj6OdZPIjIzqD",
  "src": "https://wx-love-img.afunapp.com/FhGRLUokkOGkZ9WLj6OdZPIjIzqD"
}

2. upload_base64 - 上传 Base64 图片

上传 Base64 编码的图片，支持压缩：

// 在 AI 助手中使用
upload_base64({
  base64Data: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  compress: false,    // 可选，是否压缩，默认 false
  quality: 60,        // 可选，压缩质量 1-100，默认 60
  timeout: 30000      // 可选，默认 30 秒
})

参数说明：

base64Data (必填): Base64 编码的图片数据，可以带 data:image/...;base64, 前缀，也可以是纯 Base64 字符串
compress (可选): 是否压缩图片（会转换为 JPEG 格式），默认 false
quality (可选): 压缩质量（1-100），仅在 compress=true 时生效，默认 60
timeout (可选): 上传超时时间（毫秒），默认 30000

返回结果：

{
  "key": "FhGRLUokkOGkZ9WLj6OdZPIjIzqD",
  "hash": "FhGRLUokkOGkZ9WLj6OdZPIjIzqD",
  "src": "https://wx-love-img.afunapp.com/FhGRLUokkOGkZ9WLj6OdZPIjIzqD"
}

使用示例

示例 1: 上传单个图片

用户: 请帮我上传这个图片 ~/Desktop/screenshot.png

AI: 我来帮您上传...
[调用 upload_file 工具]
✅ 上传成功！图片链接: https://wx-love-img.afunapp.com/FhGRLUokk...

示例 2: 上传并压缩图片

用户: 请上传这个图片并压缩到 50% 质量

AI: 我来处理...
[读取图片，转换为 Base64，调用 upload_base64 工具并设置 compress=true, quality=50]
✅ 上传成功！压缩后的图片链接: https://wx-love-img.afunapp.com/...

示例 3: 批量上传

用户: 请上传 ./images 文件夹中的所有 PNG 图片

AI: 我来扫描并上传...
[扫描文件夹，逐个调用 upload_file]
已上传 5 张图片：
1. image1.png -> https://...
2. image2.png -> https://...
...

示例 4: 转换 Markdown 图片链接

用户: 请将 README.md 中的本地图片都上传到云端，并更新链接

AI: 我来处理...
[找到本地图片 -> 上传 -> 替换链接]
已更新 3 个图片链接，文件已保存。

开发

开发模式

npm run dev

构建

npm run build

启动服务

npm start

技术细节

上传凭证获取

服务会自动从内部 API 获取上传凭证，无需手动配置。

CDN 域名

上传成功后，文件会通过以下 CDN 域名访问：

https://wx-love-img.afunapp.com/{hash}

图片压缩

使用 Jimp 库进行图片压缩，压缩后的图片会转换为 JPEG 格式。

部署到云端

方式 1: 发布到 npm

npm login

发布包：

npm publish

其他用户可以通过 npx 使用：

npx ivy-upload-mcp

方式 2: 部署到服务器

将项目上传到服务器
安装依赖并构建：

npm install
npm run build

使用 PM2 或其他进程管理器运行：

pm2 start dist/index.js --name ivy-upload-mcp

方式 3: Docker 部署

构建并运行：

docker build -t ivy-upload-mcp .
docker run ivy-upload-mcp

API 参考

工具列表

upload_file

上传本地文件到七牛云存储。

| 参数 | 类型 | 说明 | 必填 | 默认值 | |------|------|------|------|--------| | file | string | 文件路径 | 是 | - | | timeout | number | 超时时间（毫秒） | 否 | 30000 |

upload_base64

上传 Base64 编码的图片到七牛云存储。

| 参数 | 类型 | 说明 | 必填 | 默认值 | |------|------|------|------|--------| | base64Data | string | Base64 编码的图片数据 | 是 | - | | compress | boolean | 是否压缩图片 | 否 | false | | quality | number | 压缩质量（1-100） | 否 | 60 | | timeout | number | 超时时间（毫秒） | 否 | 30000 |

返回结果

两个工具都返回相同的结果格式：

{
  key: string;   // 文件唯一标识
  hash: string;  // 文件哈希值
  src: string;   // 文件访问 URL
}

故障排查

1. 上传失败

可能原因：

网络连接问题
文件过大（超过七牛云限制）
上传凭证获取失败

解决方法：

检查网络连接
尝试压缩图片后上传
查看错误日志获取详细信息

2. 无法访问上传的文件

可能原因：

CDN 域名配置问题
文件尚未同步到 CDN

解决方法：

稍等片刻后重试
检查返回的 URL 是否正确
确认七牛云存储空间的访问权限设置

3. 服务无法启动

可能原因：

Node.js 版本过低
依赖未正确安装

解决方法：

确认 Node.js 版本 >= 18
重新安装依赖：npm install
查看启动日志

4. 图片压缩失败

可能原因：

图片格式不支持
图片数据损坏

解决方法：

使用 PNG、JPEG 等常见格式
确认 Base64 数据完整
不使用压缩选项直接上传

常见问题

Q: 支持哪些图片格式？

A: 支持所有七牛云支持的格式，包括 PNG、JPEG、GIF、WebP、BMP 等。压缩功能会将图片转换为 JPEG 格式。

Q: 有文件大小限制吗？

A: 七牛云对单个文件有大小限制（通常为 10MB）。建议大文件使用压缩功能。

Q: 压缩会影响图片质量吗？

A: 是的，压缩会降低图片质量。可以通过 quality 参数控制压缩程度（1-100，值越大质量越高）。

Q: 可以上传非图片文件吗？

A: upload_file 工具可以上传任何文件类型，但 upload_base64 主要用于图片，且压缩功能仅支持图片。

Q: 上传的文件会保存多久？

A: 文件保存时长取决于七牛云存储空间的配置，通常是永久保存。

Q: 如何删除已上传的文件？

A: 需要通过七牛云控制台或 API 进行删除操作，本服务不提供删除功能。

技术栈

Node.js + TypeScript
MCP SDK
Axios
Form-Data
Jimp（图片处理）
七牛云存储

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.3

添加图片压缩功能
使用 Jimp 替代 Sharp
优化错误处理

v1.0.0

初始版本发布
支持文件和 Base64 上传
自动获取上传凭证

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Ivy Upload MCP 服务

功能特性

安装

本地安装

从 npm 安装

配置

在 Cursor 中配置

在 Claude Desktop 中配置

使用方法

1. upload_file - 上传文件

2. upload_base64 - 上传 Base64 图片

使用示例

示例 1: 上传单个图片

示例 2: 上传并压缩图片

示例 3: 批量上传

示例 4: 转换 Markdown 图片链接

开发

开发模式

构建

启动服务

技术细节

上传凭证获取

CDN 域名

图片压缩

部署到云端

方式 1: 发布到 npm

方式 2: 部署到服务器

方式 3: Docker 部署

API 参考

工具列表

upload_file

upload_base64

返回结果

故障排查

1. 上传失败

2. 无法访问上传的文件

3. 服务无法启动

4. 图片压缩失败

常见问题

Q: 支持哪些图片格式？

Q: 有文件大小限制吗？

Q: 压缩会影响图片质量吗？

Q: 可以上传非图片文件吗？

Q: 上传的文件会保存多久？

Q: 如何删除已上传的文件？

技术栈

许可证

贡献

相关链接

更新日志

v1.0.3

v1.0.0