基于 ModelScope (魔搭社区) API 的 MCP 文生图服务

这是一个符合 Model Context Protocol (MCP) 标准的服务端实现。它允许 Claude Desktop、Trae 或其他 MCP 客户端调用 ModelScope 的强大 AI 模型（如 Qwen-Image, FLUX.1）来生成图像。

本服务运行在云端模式，不需要本地 GPU 算力，生成的图片以 URL 形式返回。

✨ 主要特性

• 多模型支持 ：内置支持通义千问 (Qwen-Image)、FLUX.1-Krea、MusePublic 等主流绘图模型。
• 云端生成 ：调用 ModelScope 异步 API，轻量级运行，直接返回图片链接。
• 参数灵活 ：支持自定义 Prompt、图像宽高（256-2048px）。
• 开箱即用 ：支持 npx 直接启动，无需复杂的本地环境配置。
• 标准协议 ：完全兼容 MCP 协议，可无缝集成到 Claude Desktop 或蚂蚁百宝箱等平台。

🛠️ 前置要求

1. Node.js : 版本 >= 18.0.0。
2. ModelScope API Key : 你需要注册 ModelScope 并获取 API Key（通常是免费额度或按量付费）。

🚀 快速开始 (安装与配置)

你可以选择通过 npx 运行（推荐）或 本地安装 。

方法一：通过 Claude Desktop 使用 (最简便)

直接修改 Claude Desktop 的配置文件，添加以下内容即可。

配置文件路径 ：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加配置 ：

JSON

{
  "mcpServers": {
    "modelscope-t2i": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-t2i" 
      ],
      "env": {
        "API_KEY": "你的_MODELSCOPE_API_KEY",
        "BASE_URL": "https://api-inference.modelscope.cn/"
      }
    }
  }
}

注意 ：

1. 请将 你的_MODELSCOPE_API_KEY 替换为真实的密钥。
2. mcp-t2i 是 npm 包名，请确保与实际发布包名一致。

方法二：百宝箱/Trae 配置

在支持 MCP 的 IDE 或工具箱中，参考以下配置：

• 运行命令 (Command) : npx
• 参数 (Args) : ["-y", "mcp-t2i"]
• 环境变量 (Environment Variables) :
• API_KEY: ms-xxxxxxxxxxxxxxxx (必填)

方法三：本地开发/源码运行

如果你想克隆代码进行修改：

Bash

# 1. 克隆项目
git clone https://github.com/your-repo/mcp-t2i.git
cd mcp-t2i

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 配置 MCP (指向本地构建文件)
# 在 config.json 中将 command 改为 "node"，args 改为 ["/path/to/dist/index.js"]

🧰 工具列表 (Tools)

本服务提供以下两个核心工具供 AI 调用：

1. generate_ai_image

核心功能，根据描述生成图片。

• 功能 ：提交绘图任务并等待完成，返回图片 URL。
• 参数 ：
• prompt (必填, string): 画面描述提示词（建议使用英文描述以获得最佳效果，但也支持中文）。
• model (选填, string): 模型 ID，默认为 Qwen/Qwen-Image。
• width (选填, int): 图片宽度，默认 1024。范围 256-2048，需为 64 的倍数。
• height (选填, int): 图片高度，默认 1024。范围 256-2048，需为 64 的倍数。

2. list_available_models

查询当前支持的模型列表。

• 功能 ：返回可用的模型 ID 及其描述。
• 参数 ：无。
• 返回示例 ： JSON

  [
    "Qwen/Qwen-Image",
    "black-forest-labs/FLUX.1-Krea-dev",
    "MusePublic/flux-high-res"
  ]

🗣️ 使用示例

配置成功后，你可以直接对 Claude 或 IDE 助手说：

"帮我用通义千问模型画一张赛博朋克风格的猫，尺寸要方形的。"

"查看一下现在有哪些可用的画图模型？"

"生成一张海边日落的照片，使用 FLUX 模型。"

❓ 常见问题 (FAQ)

Q1: 为什么提示 "API_KEY not configured"? A : 请确保在 MCP 客户端的配置文件（json）中的 env 字段里正确填写了 API_KEY。不要依赖项目文件夹里的 .env 文件，因为 npx 运行时可能读取不到。

Q2: Windows 下报错 "spawn npx ENOENT" 或 "mkdir" 错误？ A : 这通常是 npm 缓存路径过长或依赖版本冲突导致的。

1. 尝试清理缓存：npm cache clean --force
2. 或者尝试全局安装：npm install -g mcp-t2i，然后将配置里的 command 改为 mcp-t2i（Windows 下可能需要写 mcp-t2i.cmd）。

Q3: 图片链接有效期多久？ A : 图片链接直接来自 ModelScope 的 OSS 输出，通常有效期较长，但建议尽快下载保存重要图片，不保证永久有效。

📄 License

ISC License