TokenHub AIGC Model — MCP Server

通过 MCP（Model Context Protocol） 调用 TokenHub 大模型服务平台生图能力的 MCP Server。客户在任何支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor / 各类 AI IDE）中配置 TokenHub API Key，即可直接用自然语言调用文生图、图生图/图片编辑接口。

当前内置样例模型：custom-model-og-v2（GPT 系生图模型，同步返回）。

功能特性

• 两个工具

  • tokenhub_generate_image：文生图（POST /v1/wand/og-image/generation，同步返回）

  • tokenhub_edit_image：图生图/图片编辑（POST /v1/wand/og-image/edits，同步返回，支持 1-16 张输入图、mask 局部重绘）

• 双传输

  • stdio（默认）：本地客户端直接接入，零部署

  • streamable-http：部署成远程端点，供外部客户/团队远程接入

• 灵活配置：API Key、站点域名、模型名均可通过环境变量配置；单次调用可覆盖域名/模型（切换站点或模型无需改配置）

Related MCP server: MCP OpenAI Image Generation Server

快速开始

方式一：stdio（本地接入，推荐先用这个）

在 MCP 客户端配置中新增一个命令类型的 MCP Server：

{
  "mcpServers": {
    "tokenhub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tokenhub-aigc-model"],
      "env": {
        "TOKENHUB_API_KEY": "你的 TokenHub API Key",
        "TOKENHUB_BASE_URL": "https://tokenhub.tencentmaas.com",
        "TOKENHUB_MODEL": "custom-model-og-v2"
      },
      "description": "TokenHub 生图 MCP"
    }
  }
}

配置后即可对话：「帮我画一只在竹林中跳舞的小猫，2048x2048」。

方式二：Streamable HTTP（远程部署）

{
  "mcpServers": {
    "tokenhub": {
      "url": "https://你的服务域名/mcp",
      "headers": { "x-mcp-auth-token": "部署时设置的 MCP_AUTH_TOKEN" }
    }
  }
}

环境变量

站点域名

TokenHub 按地域分站部署，不同站点的客户需填写对应域名。默认是国内站广州：

工具参数说明

tokenhub_generate_image（文生图）

tokenhub_edit_image（图生图/编辑）

共享上文大部分参数，额外：

返回：图片 URL 列表、request_id（排查问题用）、total_tokens（计费用）；response_format=b64_json 时附带 base64 图片块供直接展示。

错误处理

• 工具调用失败返回 isError: true，错误信息包含 status、上游错误 code、request_id。

• 出现权限/限流/参数错误时，请保留 request_id 提交给 TokenHub 技术支持定位。

• 未配置 TOKENHUB_API_KEY 时，工具调用直接返回明确提示（server 可正常启动）。

HTTP 模式部署（远程）

# 本地启动（默认 stdio）
npx -y tokenhub-aigc-model

# HTTP 模式
TOKENHUB_API_KEY=xxx MCP_AUTH_TOKEN=部署密钥 \
  npx -y tokenhub-aigc-model --transport=http --port=3000 --host=127.0.0.1

端点：

• POST /mcp、GET /mcp：MCP 协议入口

• GET /health：健康检查

部署到公网时务必：

1. 设置 MCP_AUTH_TOKEN，或在前置网关/反向代理（如 EdgeOne、CLB、Nginx）做鉴权；

2. 使用 HTTPS；

3. base_url 支持单次覆盖，仅建议在可信环境下开放。

开发与发布

npm install        # 安装依赖
npm run build      # TypeScript 构建到 dist/
npm test           # 单元测试 + stdio/HTTP 冒烟测试（共 20 个用例）
npm pack --dry-run # 查看发布内容

发布到 npmjs（当前 registry 若是腾讯镜像，需显式指定）：

npm run build
npm version patch
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.1.0 && git push --tags

⚠️ 重要提醒

1. 开白：custom-model-og-v2 为测试模型，需联系 TokenHub 产品/后台人员提交 UIN 和 Appid 开白后方可使用；未开白调用会返回权限错误。

2. API Key：请在 TokenHub 控制台 为对应模型创建专属 Key；Key 只在创建时展示一次，请妥善保存。

3. 计费：TokenHub 按 Token 计费（约 10 元/百万 token），小时结算。n>1 或多张输入图会显著放大消耗，请商务及时为客户申请折扣。

4. 费用公式（人民币）：文本输入 token×3.35 + 文本缓存输入×0.8375 + 图片输入×5.36 + 图片缓存输入×1.34 + 输出图片×20.1 = 单次任务 token 消耗（换算系数与汇率有关，当前系数 6.7）。

License

Apache-2.0