TokenHub MCP

TokenHub MCP（TokenHub模型上下文协议服务） 是给本地编程客户端使用的 stdio（标准输入输出） 模式 MCP（模型上下文协议）服务。工具默认全部关闭；客户端配置里必须显式写入 TOKENHUB_MCP_ENABLED_TOOLS（TokenHub MCP启用工具列表） 后，本地 MCP（模型上下文协议）进程才会向客户端声明对应工具。模型调用工具时，本地 MCP（模型上下文协议）进程会转发到 nanoapi（网关程序） 的 /api/service/*（服务接口），并按用户已购买或后台授予的服务套餐扣费。

当前 npm 包

• package（包名）: @tokenhub-cash/mcp
• registry（包注册仓库）: https://registry.npmjs.org/
• version（当前版本）: 0.1.7
• bin（二进制入口）: tokenhub-search-mcp
• runtime（运行时）: Node.js（节点运行时） >= 18.18
• install command（安装命令）: npx -y @tokenhub-cash/mcp

架构

调用链路：

用户提问
  -> 客户端 MCP host（模型上下文协议宿主）
  -> 本地 stdio MCP server（标准输入输出MCP服务）
  -> POST https://api.tokenhub.market/api/service/*
  -> nanoapi（网关程序）鉴权、路由、扣费
  -> 服务渠道池
  -> 服务结果回到模型上下文

本地 MCP（模型上下文协议）只做三件事：

1. 从客户端传入的 environment（环境变量配置） 读取 TOKENHUB_MCP_ENABLED_TOOLS（TokenHub MCP启用工具列表）。
2. 只向客户端声明显式启用的工具。
3. 从客户端传入的 environment（环境变量配置） 读取 TOKENHUB_API_KEY（TokenHub接口密钥）。
4. 把工具参数转成 /api/service/*（服务接口） 请求，并把网关响应格式化为文本结果。

鉴权不走 OAuth（开放授权）。当前行业里本地 stdio（标准输入输出） MCP（模型上下文协议）的主流做法是由客户端配置 MCP（模型上下文协议）子进程的 environment（环境变量配置），子进程启动后从自己的进程环境读取密钥。这里的 TOKENHUB_API_KEY（TokenHub接口密钥） 就是用户自己的 master_key（身份主密钥），由安装命令或配置文件写入客户端 MCP（模型上下文协议）配置；TOKENHUB_MCP_ENABLED_TOOLS（TokenHub MCP启用工具列表） 同样保存在客户端配置里。

Tools

工具名：search（搜索）

输入：

• query（单个查询词）: 单次搜索词
• queries（批量查询词）: 最多 5 个搜索词
• count（返回数量）: 默认 8，最大 20
• freshness（时效过滤）: 可选，例如 day（天）、week（周）、month（月）、year（年）
• summary（摘要开关）: 默认 true（开启）

每个查询词会发起一次 /api/service/search（服务搜索接口） 请求；网关成功写入 service_request_billings（服务请求事实表） 后扣减搜索套餐额度。

工具名：image_generate（图片生成）

• prompt（提示词）: 必填
• n（图片数量）: 默认 1，最大 4
• aspect_ratio（宽高比）: 默认 1:1
• response_format（响应格式）: 默认 url

工具名：video_generate（视频生成）

• prompt（提示词）: 必填
• duration（时长秒）: 默认 6
• resolution（分辨率）: 默认 768P
• first_frame_image（首帧图片）: 可选 URL 或 data URL

当前视频接口是异步任务创建接口，成功后返回 job_id（网关任务编号）、status（状态）、task_id（上游任务编号） 与 poll_after_seconds（建议轮询秒数），不在 MCP（模型上下文协议）进程内长轮询。

工具名：video_status（视频任务查询）

• job_id（网关任务编号）: 必填，来自 video_generate（视频生成）

video_status（视频任务查询） 调用 /api/service/video/jobs/{job_id}（视频任务查询接口）。当 status（状态）=succeeded（已成功） 时返回 asset_url（资源地址）、asset_expires_at（资源地址过期时间）、file_id（文件编号）、video_width（视频宽度） 与 video_height（视频高度）；轮询查询不重复消耗视频生成套餐额度。

工具名：music_generate（音乐生成）

• prompt（提示词）: 必填
• lyrics（歌词）: 可选；不传歌词且不是纯音乐时，默认启用 lyrics_optimizer（歌词优化）
• output_format（输出格式）: 默认 url
• audio_setting（音频设置）: 默认 mp3/44100/256000

当前音乐接口是异步任务创建接口，成功后返回 job_id（网关任务编号）、status（状态） 与 poll_after_seconds（建议轮询秒数），不在 MCP（模型上下文协议）进程内长时间等待上游生成。

工具名：music_status（音乐任务查询）

• job_id（网关任务编号）: 必填，来自 music_generate（音乐生成）

music_status（音乐任务查询） 调用 /api/service/music/jobs/{job_id}（音乐任务查询接口）。当 status（状态）=succeeded（已成功） 时返回 audio_url（音频地址）、asset_url（资源地址） 与 asset_expires_at（资源地址过期时间）；轮询查询不重复消耗音乐生成套餐额度。

工具名：vision_analyze（图片理解）

• prompt（提示词）: 必填，对图片的问题或任务
• image_base64（图片base64）: 必填，图片二进制的 base64（基础64编码）字符串；也兼容 data URL（数据地址），但不接受公网 URL（统一资源定位符）或本地文件路径

工具名：stock_query（股票查询）

• ticker（股票代码）: 必填，单个股票代码或逗号分隔列表，一次最多 3 个；示例 600519.SH（贵州茅台）、0700.HK（腾讯控股）、AAPL.US（苹果）
• query_type（查询类型）: 默认 realtime_price（实时价），可选 close_summary（收盘摘要）、open_summary（开盘摘要）、realtime_tech（实时技术指标）、hk_realtime_price（隐藏实时价类型）
• time（查询时间）: 可选，格式 YYYY-MM-DD HH:MM:SS（年月日时分秒），秒必须为 00

stock_query（股票查询） 调用 /api/service/stock（服务股票查询接口）。网关侧使用 Kimi Coding Plan（Kimi编程套餐）专业数据库 POST /coding/v1/tools（工具接口），固定方法为 get_stock_realtime_price（获取股票实时价格），成功后统一返回 rows（行数据）、files（文件） 与上游文本信息。股票代码必须带支持的市场后缀：.SH（上交所）、.SZ（深交所）、.BJ（北交所）、.HK（港股） 或 .US（美股）；其中 .US（美股） 当前只把 realtime_price（实时价） 作为已验证能力，close_summary（收盘摘要）、open_summary（开盘摘要） 与 realtime_tech（实时技术指标） 可能由上游返回不支持。该工具只返回行情数据，不应被客户端或模型包装成投资建议。

上述工具分别需要用户拥有对应的服务套餐，例如 service-search-monthly-30（网络搜索月套餐）、service-image-basic-30（初级文生图月套餐）、service-video-basic-30（初级视频生成月套餐）、service-music-basic-30（初级音乐生成月套餐） 与 service-stock-basic-30（股票查询月套餐）。拥有视频套餐时一键配置会同时启用 video_generate（视频生成） 与 video_status（视频任务查询）；拥有音乐套餐时一键配置会同时启用 music_generate（音乐生成） 与 music_status（音乐任务查询）；拥有股票套餐时一键配置会启用 stock_query（股票查询）。vision_analyze（图片理解） 当前暂不上架公开套餐，只支持后台直接授予 vision（图片理解） 服务套餐实例。一键配置脚本会根据用户已购买服务套餐生成启用列表；如果用户模型套餐里包含原生 vision（视觉） 能力模型，例如 kimi-k2.6（Kimi K2.6模型） 或后续配置的 k2.5（K2.5模型），即使用户有 vision（图片理解） 服务套餐，也默认不启用 vision_analyze（图片理解工具），避免和模型原生能力冲突。

vision_analyze（图片理解） 不读取客户端本地文件，也不会把相对路径、绝对路径或公网 URL（统一资源定位符）转换成图片内容。调用方必须在客户端侧自行读取图片并转成 base64（基础64编码）后再传入；原始 JPEG（联合图像专家组图片）base64（基础64编码）常见的 /9j/ 开头会被视为合法图片内容，不会被误判成本地路径。

客户端安装示例

Claude Code（Claude代码）：

claude mcp add -s user -e TOKENHUB_API_KEY=mk_xxx tokenhub-tools -- npx -y @tokenhub-cash/mcp

启用搜索和图片生成时：

claude mcp add -s user -e TOKENHUB_API_KEY=mk_xxx -e TOKENHUB_MCP_ENABLED_TOOLS=search,image_generate tokenhub-tools -- npx -y @tokenhub-cash/mcp

Kimi CLI（Kimi命令行）：

kimi mcp add -t stdio -e TOKENHUB_API_KEY=mk_xxx tokenhub-tools -- npx -y @tokenhub-cash/mcp

OpenCode（OpenCode）当前按官方 opencode.json（配置文件） 的 mcp（模型上下文协议） 配置块写入，不使用不存在的 opencode mcp add（添加MCP命令）。OpenCode（OpenCode）侧建议把 MCP server key（模型上下文协议服务键名）写成 tokenhub（TokenHub），这样暴露给模型的工具名会是 tokenhub_search（TokenHub搜索工具）。Claude Code（Claude代码）、Kimi CLI（Kimi命令行）、OpenClaw（OpenClaw）与 Hermes（Hermes）统一使用 tokenhub-tools（TokenHub工具） 作为 MCP server key（模型上下文协议服务键名），避免客户端界面继续显示旧的 tokenhub-search（TokenHub搜索） 名称。

OpenClaw（OpenClaw）使用 openclaw mcp set（设置MCP命令）。

Hermes（Hermes）写入 config.yaml（配置文件） 的 mcp_servers（MCP服务器配置）。

环境变量

• TOKENHUB_API_KEY（TokenHub接口密钥）: 必填，用户自己的 master_key（身份主密钥）
• TOKENHUB_MCP_ENABLED_TOOLS（TokenHub MCP启用工具列表）: 逗号分隔，默认空。可选值为 search（搜索）、image_generate（图片生成）、video_generate（视频生成）、video_status（视频任务查询）、music_generate（音乐生成）、music_status（音乐任务查询）、vision_analyze（图片理解）、stock_query（股票查询）
• TOKENHUB_BASE_URL（TokenHub基础地址）: 默认 https://api.tokenhub.market
• TOKENHUB_MCP_LOG_LEVEL（MCP日志级别）: error（错误）、warn（警告）、info（信息）、debug（调试），默认 info（信息）
• TOKENHUB_MCP_DEBUG（MCP调试开关）: 设置为 1 时在 stderr（标准错误） 输出更完整的上游响应
• TOKENHUB_MCP_TIMEOUT_MS（MCP超时时间毫秒）: 默认 30000

日志只写 stderr（标准错误），stdout（标准输出） 只保留给 MCP JSON-RPC（模型上下文协议远程过程调用）通信。

本地验证

默认 npm run smoke（冒烟测试） 只校验默认不暴露工具；设置 TOKENHUB_MCP_SMOKE_EXPECT_TOOLS（MCP冒烟期望工具列表） 可校验工具开关和 list_tools（工具列表）。股票工具可用本地 mock server（模拟服务）覆盖参数归一化、接口转发、request_id（请求编号） 精度保持和非法股票代码拒绝：

TOKENHUB_MCP_ENABLED_TOOLS=stock_query TOKENHUB_MCP_SMOKE_CALL_STOCK=1 npm run smoke