TokenHub AIGC Model — MCP Server

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

对话式选模型

不需要在配置里改模型。MCP 内置模型注册表，AI 会先通过 tokenhub_list_models 查询可用模型，再按你对话中指定的模型调用对应工具并构建请求：

用户："用 kling-video-v3 生成一个海边日落的视频" → AI 查模型注册表 → 调用 tokenhub_kling_text_to_video(model="kling-video-v3", ...) → 返回 task_id → 轮询 tokenhub_kling_get_task 直到拿到视频

TOKENHUB_MODEL 环境变量仅作为兜底默认值（不传 model 时使用），日常使用建议直接对话指定模型。

快速开始

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

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

| 客户端 | 配置位置 | | --- | --- | | WorkBuddy | ~/.workbuddy/mcp.json，然后「连接器管理 → 自定义连接器 → 信任」 | | Claude Desktop | claude_desktop_config.json | | Cursor | Settings → MCP → Add new 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_TIMEOUT_MS": "120000"
      },
      "description": "TokenHub 生图/生视频 MCP"
    }
  }
}

TOKENHUB_MODEL 可不配：默认在对话中指定模型；不指定时生图用 custom-model-og-v2、视频用 kling-video-v3。

⚠️ 超时配置：TOKENHUB_TIMEOUT_MS（毫秒）为单次请求超时，默认 120000（120 秒）。文生图/图生图为同步接口，高画质/大尺寸下生成耗时可能较长；若日志出现"请求超时"，请调大该值（如 300000）。

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

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

环境变量

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | TOKENHUB_API_KEY | 是（调用时报错） | - | TokenHub 控制台获取的 API Key，请求头 Authorization: Bearer <key> | | TOKENHUB_BASE_URL | 否 | https://tokenhub.tencentmaas.com | 站点域名（见下），末尾无需斜杠 | | TOKENHUB_MODEL | 否 | custom-model-og-v2 | 兜底默认模型：仅当调用不传 model 时生效。推荐在对话中直接指定模型 | | TOKENHUB_TIMEOUT_MS | 否 | 120000 | 单次请求超时（毫秒）。生图为同步接口，高画质/大尺寸生成耗时长，超时请调大（如 300000）；非法值自动回退默认 | | MCP_AUTH_TOKEN | 否（HTTP 模式建议） | - | HTTP 模式可选鉴权，设置后 /mcp 请求必须携带 x-mcp-auth-token 请求头 |

站点域名

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

| 站点 | 域名（示例） | | --- | --- | | 国内站 · 广州 | https://tokenhub.tencentmaas.com（默认） | | 其他站点（国内新加坡 / 国际站广州、新加坡、美西等） | 请联系 TokenHub 商务/技术支持获取对应域名，填入 TOKENHUB_BASE_URL 或单次调用传 base_url |

工具总览

| 工具 | 能力 | 适用模型 | 文档 | | --- | --- | --- | --- | | tokenhub_list_models | 查询可用模型注册表（对话式选模型的入口） | - | - | | tokenhub_generate_image | 文生图（同步） | custom-model-og-v2 | docs/og-image.md | | tokenhub_edit_image | 图生图 / 图片编辑（同步） | custom-model-og-v2 | docs/og-image.md | | tokenhub_kling_text_to_video | 可灵文生视频（异步提交） | kling-video-v3 等 4 款 | docs/kling.md | | tokenhub_kling_image_to_video | 可灵图生视频（异步提交） | kling-video-v3 等 4 款 | docs/kling.md | | tokenhub_kling_get_task | 可灵任务查询 / 轮询 | 所有 kling 视频任务 | docs/kling.md |

模型列表总表

以 tokenhub_list_models 实时返回为准，下表为当前注册内容（v0.3.0）。

| 模型 | 厂商 | 能力 | 可用工具 | 文档 | | --- | --- | --- | --- | --- | | custom-model-og-v2 | og-image | 文生图 / 图生图 | generate_image, edit_image | docs/og-image.md | | kling-video-v3（默认） | kling | 文生视频 / 图生视频 | kling_text_to_video, kling_image_to_video (+ get_task 轮询) | docs/kling.md | | kling-video-v3-turbo | kling | 文生视频 / 图生视频 | 同上 | docs/kling.md | | kling-video-v2.6 | kling | 文生视频 / 图生视频 | 同上 | docs/kling.md | | kling-video-v2.5-turbo | kling | 文生视频 / 图生视频 | 同上 | docs/kling.md |

WorkBuddy 对话示例

示例 1：文生图（og-image，同步）

用户：画一只在竹林中跳舞的小猫，2048x2048

AI（内部动作）：tokenhub_list_models → 发现 custom-model-og-v2 → 调用 tokenhub_generate_image({ model: "custom-model-og-v2", prompt: "一只在竹林中跳舞的小猫", size: "2048x2048" })

AI 返回：图片 URL + request_id + token 用量

示例 2：可灵文生视频（异步两段式）

用户：用 kling-video-v3 生成 5 秒 16:9 的视频：黄昏海滩上女孩看日落

AI（内部动作）：tokenhub_list_models → 调用 tokenhub_kling_text_to_video({ model: "kling-video-v3", prompt: "黄昏海滩上女孩看日落", settings: { aspect_ratio: "16:9", duration: 5 } })

AI 返回：task_id: 251435731-WandVideo-xxxx，并说明："任务已提交，视频生成需要几分钟，我可以帮你持续查询进度。"

用户：查询进度

AI（内部动作）：tokenhub_kling_get_task({ task_id: "251435731-WandVideo-xxxx" }) → status=processing → 回复："正在生成中，约 3~5 秒后再查一次。"

用户：再查一下

AI（内部动作）：tokenhub_kling_get_task(...) → status=succeeded → 返回视频地址："生成完成！视频链接：https://...mp4（临时链接，请及时保存）"

示例 3：可灵图生视频

用户：用这张图作为首帧，让画面中的猫转头，模型用 kling-video-v3

AI（内部动作）：tokenhub_list_models → 调用 tokenhub_kling_image_to_video({ model: "kling-video-v3", contents: [{ type: "prompt", text: "让画面中的猫自然转头" }, { type: "first_frame", url: "https://...jpg" }] }) → 拿 task_id → 轮询 tokenhub_kling_get_task → 返回视频

错误处理

• 工具调用失败返回 isError: true，错误信息包含 status、上游错误 code、request_id。
• HTTP 200 但业务 code != 0（可灵等统一外壳接口）：同样按错误透传 code 与 message。
• 出现权限/限流/参数错误时，请保留 request_id 提交给 TokenHub 技术支持定位。
• 未配置 TOKENHUB_API_KEY 时，工具调用直接返回明确提示（server 可正常启动，tokenhub_list_models 不受影响）。

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 冒烟测试（共 37 个用例）
npm pack --dry-run # 查看发布内容

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

npm run build
npm test
npm version 0.3.0   # 升版本（或手改 package.json）
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.3.0 && git push --tags

⚠️ 重要提醒

1. 开白：TokenHub 模型多为白名单制，需联系 TokenHub 产品/后台人员提交 UIN 和 Appid 开白后方可使用；未开白调用会返回权限错误（保留 request_id 排查）。
2. API Key：请在 TokenHub 控制台 为对应模型创建专属 Key；Key 只在创建时展示一次，请妥善保存。
3. 计费：TokenHub 按 Token 计费（约 10 元/百万 token），小时结算。生视频单次任务消耗远高于生图（可达数十万 token），请商务及时为客户申请折扣。
4. 同步生图超时：文生图/图生图为同步接口，单次请求可能耗时较长（默认超时 120 秒）。如遇"请求超时"，请在 MCP 配置中调大 TOKENHUB_TIMEOUT_MS（如 300000）。
5. 视频临时链接：tokenhub_kling_get_task 返回的视频地址为临时链接（约 12 小时有效），请及时下载转存。

License

Apache-2.0