shumi

@shumi-ai/mcp

Shumi 加密货币交易情报 MCP 服务——让任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、Agent）都能使用与 shumi CLI 相同的市场情报。

这是对 Shumi 数据 API 的轻量封装，涵盖价格、趋势、资金费率、情绪、叙事、市场状态、综合信号、交易对／Delta 中性思路、现实世界资产、持有者和钱包追踪，以及转录内容摘要。所有工具均为只读。

快速开始

你需要一个 Shumi API 密钥（shumi_sk_…）。请在 https://shumi.ai 创建。

Claude Desktop / Claude Code

将以下内容添加到 MCP 配置中（claude_desktop_config.json；Claude Code 则使用 claude mcp add）：

{
  "mcpServers": {
    "shumi": {
      "command": "npx",
      "args": ["-y", "@shumi-ai/mcp"],
      "env": {
        "SHUMI_TOKEN": "shumi_sk_your_key_here"
      }
    }
  }
}

重启客户端。shumi 工具（例如 get_coin_risk、get_market_health、ask_shumi）会自动显示。

Cursor

~/.cursor/mcp.json 使用与上述相同的 command / args / env 结构。

插件目录

本仓库根目录还提供 plugin.json 和 mcp.json，因此可以作为 Agent Plugin 从 Cursor 的目录以及任何支持该标准的客户端安装。

以这种方式安装时，请在启动客户端前于环境中设置 SHUMI_TOKEN。Agent Plugins 架构只接受字面量环境值，没有用于密钥的占位符，因此清单会有意省略 env，而不会提供 ${SHUMI_TOKEN} 字符串；该字符串会原样传递，导致密钥无效。

工具

类型化（确定性）： get_coin_risk、lookup_coin、resolve_coin、get_coin_sentiment、 get_coin_historical、get_market_health、get_market_crossing、get_global_market、 get_prices、scan_trends、scan_coins、get_market_sentiment、list_narratives、 get_narrative、list_categories、get_category、get_funding_momentum、get_funding_alerts、 get_regime、get_signal、get_signal_quality、get_pair_suggestions、list_rwa_assets、 get_rwa_asset、get_unlocks、get_unlock_calendar、get_holders、get_wallets、get_futures_signals、get_basket、 get_transcripts。

现实世界资产（list_rwa_assets、get_rwa_asset）涵盖在 Hyperliquid builder DEX 上作为永续合约交易的股票、ETF、商品、指数和外汇。它们不是加密代币，币种工具无法找到它们。

自由形式： ask_shumi（自然语言问题——Shumi 会进行分类、获取数据并综合回答）和 search_web。

返回列表的工具接受 top（保留前 N 项）和 fields（以逗号分隔要保留的键），以节省令牌。

资源： shumi://capabilities（数据范围）和 shumi://billing/tier（你当前的使用权限）。

配置

环境变量	默认值	用途
SHUMI_TOKEN	—	API 密钥（shumi_sk_*）。必填。
SHUMI_API_URL	生产环境 coinrotator-ai 端点	覆盖 API 基础 URL。
SHUMI_WALLET	—	添加到 NLP 查询上下文中的钱包地址。

配额控制（free / access / pro 层级和按次付费）在服务端执行，与 CLI 完全相同——超出配额时会返回结构化错误，并附上可操作的提示。

远程（HTTP）

用于托管式多用户部署：

PORT=8787 SHUMI_MCP_ALLOWED_ORIGINS=https://yourapp.com npm run start:http

每个请求都使用独立的密钥标头进行身份验证；该令牌会随每个请求转发到上游 API。端点：POST /mcp，健康检查：GET /health。

从 Claude 连接（static_headers）

Claude 支持通过请求标头填写固定凭据，因此不需要 OAuth 服务。在 添加自定义连接器 → 请求标头中，组织管理员填写：

字段	值
URL	https://mcp.shumi.ai/mcp
标头名称	Authorization
标头值	Bearer shumi_sk_…

x-api-key: shumi_sk_… 也可以，省略 Bearer 前缀的 Authorization 值同样可以——管理员需要手动填写一次，填错的组合会被安全拒绝，而且不会显示错误，因此接受这三种格式。如果两者都存在，则优先使用 x-api-key，因为设置了它就说明管理员有意使用它。

不要将密钥放在 URL 中。 MCP 授权规范禁止在 URI 查询字符串中放入访问令牌，Anthropic 也将 URL 中的凭据记录为安全漏洞——URL 会出现在服务器日志、代理和浏览器历史记录中。?shumiToken= / ?config= 查询形式仅因 Smithery 会以这种方式注入会话配置而存在。

团队购买前需要了解一点：static_headers 凭据是组织共享的，并非按用户区分。所有通过该连接器连接的人共用一个 Shumi 账户、一份免费套餐额度和一个配额。按用户计量需要使用 OAuth——参见 docs/oauth-plan.md。

未通过身份验证的调用会收到**200 和带内 AUTH_REQUIRED 错误，而不是 401**。这是有意设计的：Claude 会将 401 视为 OAuth 流程的起点，而没有授权服务器的服务会让客户端进入无法完成的握手流程。401 路径确实存在，但受 SHUMI_MCP_AUTH_SERVER 控制，因此只有在有可指向的授权服务器后才会启用。

服务是无状态的。 一个端点支持两个协议版本：

• 2026-07-28 — 不需要 initialize，也不需要 Mcp-Session-Id。请求在标头中携带自身的路由信息（Mcp-Method，以及 tools/call 请求中的 Mcp-Name），并在 params._meta 中携带协议封装，因此中间层无需解析请求正文即可路由和计量调用。
• 2025-11-25 及更早版本 — 仍受支持。旧客户端继续使用其 initialize 握手，但每次交互都由各自的实例响应，而非通过会话处理。

由于请求处理结束后不会保留任何状态，GET 和 DELETE（2025 版的会话操作）会返回 405；原先在此使用的会话可调参数——SHUMI_MCP_SESSION_TTL_MS、SHUMI_MCP_MAX_SESSIONS、SHUMI_MCP_SESSION_SWEEP_MS——也已移除。可以安全地从任何部署中删除这些参数；未设置时，它们不会产生任何作用。它们所配置的空闲会话清理器原本用于防止存活探测不断占用堆内存；没有保留会话时，就不会出现这种情况。

开发

npm install
npm test                # unit tests (no network)
npm run inspect         # open the MCP Inspector against the stdio server
SHUMI_TOKEN=… npm start # run the stdio server

有意不公开的功能

有两个 CLI 路由没有对应的 MCP 工具，这是有意为之：

• walkforward — 路由已存在，但 Engine B 暂停期间，三个操作中有两个没有可用数据：positions 为空，outcomes 只有一条来自 2026-05-28 的记录。发布它会让调用者收到一个空数组，却没有任何原因说明。待引擎恢复后再加入。
• watch — 服务端发送事件，与 MCP 工具语义不兼容。

CLI 中其他所有有类型的功能都有对应的工具。