sifting

siftingio-mcp

这是一个 Model Context Protocol（MCP）服务， 让你的 AI 助手能够使用 SiftingIO market-data SDK （@siftingio/sdk）。服务启动后，模型可以获取实时价格、查阅 SEC/EDGAR 基本面数据、获取 OHLCV K 线、查询 13F 持仓、检查市场状态，并扫描宏观经济日历——所有功能都以工具的形式提供。

设置

npm install
npm run build

你需要一个 API 密钥，可从 https://sifting.io 获取：

export SIFTING_API_KEY=sft_...

如果需要连接到其他后端，可以通过 SIFTING_BASE_URL 和 SIFTING_WS_URL 覆盖默认值。

要在本地工作？可以将 .env.example 复制为 .env——npm run dev 和 npm start 会自动读取该文件（Node 通过 --env-file-if-exists 加载）。不过，将其接入实际的 MCP 客户端时，应通过服务的 env 块传入密钥，而不是使用文件（下文有示例）。

运行

以下是可用的工具：

• npm run build — 将 TypeScript 编译到 dist/。
• npm start — 通过 stdio 运行编译后的服务（node dist/index.js）。
• npm run start:http — 通过 Streamable HTTP 运行服务（node dist/http.js）。
• npm run dev / npm run dev:http — 使用 tsx 直接运行源代码，无需构建。
• npm test — 运行 vitest 测试套件（添加 npm run test:watch 可持续运行）。
• npm run lint / npm run format — 运行 ESLint（typescript-eslint）和 Prettier。
• npm run typecheck — 执行 tsc --noEmit。

每次推送和 PR 都会触发 CI（.github/workflows/ci.yml），依次执行相同的检查流程： 格式检查 → lint → 类型检查 → 构建 → 测试。

有一点值得注意：服务通过 stdio 使用 JSON-RPC 通信，因此 stdout 完全由协议占用。所有诊断信息都会输出到 stderr，以免干扰协议。

交互式检查

想手动试用？MCP inspector 是最简单的方式：

SIFTING_API_KEY=sft_... npx @modelcontextprotocol/inspector node dist/index.js

HTTP（Streamable HTTP）传输

如果要在远程或托管环境中运行，请使用 MCP 的 Streamable HTTP 传输，而不是 stdio：

SIFTING_API_KEY=sft_... PORT=3000 npm run start:http
# → MCP endpoint at http://127.0.0.1:3000/mcp  (POST messages, GET SSE, DELETE session)

它是有状态的：每个客户端都有自己的会话（通过 mcp-session-id 请求头跟踪）和自己的 McpServer，而整个进程共享同一个上游 SiftingIO 连接。作为安全措施，它只绑定到环回地址，并拒绝非本地浏览器的 Origin——这是 DNS 重绑定防护。使用 PORT（或 MCP_HTTP_PORT）设置端口；默认值为 3000。

如果需要身份验证，请设置 MCP_AUTH_TOKEN，服务便会要求每个请求都带上 Authorization: Bearer <token>（缺失或错误的值都会返回 401）。将其与负责处理 TLS 和令牌的反向代理搭配使用，即可安全地将服务暴露到 localhost 之外：

MCP_AUTH_TOKEN=s3cret SIFTING_API_KEY=sft_... npm run start:http

然后，将任何支持 HTTP 的 MCP 客户端指向 http://127.0.0.1:3000/mcp 即可：

claude mcp add --transport http siftingio http://127.0.0.1:3000/mcp

与 MCP 客户端搭配使用

将以下内容放入客户端配置中——例如 Claude Desktop 的 claude_desktop_config.json，或者如果你使用 Claude Code，也可以运行 claude mcp add：

{
  "mcpServers": {
    "siftingio": {
      "command": "node",
      "args": ["/absolute/path/to/siftingio-mcp/dist/index.js"],
      "env": { "SIFTING_API_KEY": "sft_..." }
    }
  }
}

工具（36）

命名空间	工具
实时（快照）	last_trade、last_quote、last_tvl
股票	stocks_search、stocks_profile、stocks_filings、stocks_filing、stocks_sections、stocks_section、stocks_risk_factors_diff、stocks_ratios、stocks_earnings、stocks_financials、stocks_financial_concept、stocks_insiders、stocks_ownership、stocks_events、stocks_compensation、stocks_screener、stocks_bars
加密货币 / 外汇	crypto_bars、forex_bars
DEX	dex_wallet
市场	markets_list、markets_status_all、markets_status、markets_hours、markets_calendar
申报方	filers_holdings
宏观	economic_calendar_list
实时（流）	ws_subscribe、ws_unsubscribe、ws_poll、ws_collect、ws_status、ws_disconnect

有几种模式值得特别说明：

支持分页的工具会接收 cursor/limit，并返回 meta.next_cursor 以获取下一页。stocks_* 列表工具——stocks_filings、stocks_earnings、stocks_insiders、stocks_ownership、stocks_events、stocks_compensation——也支持 max_items：设置该参数后，工具会自动分页，在一次调用中跨页收集最多指定数量的项目。

流量较大的工具（last_trade、last_quote、last_tvl、stocks_profile、stocks_search）附带输出架构，并在返回人类可读文本的同时提供 structuredContent，因此客户端也可以通过机器读取结果。

每个工具还带有 MCP 注解。数据工具的 readOnlyHint: true（并且 openWorldHint: true，因为它们会访问外部 API）；而会改变连接状态的 WebSocket 工具则为 readOnlyHint: false、destructiveHint: false。

结果大小上限约为 60k 个字符（参见 src/util.ts 中的 MAX_RESULT_CHARS）。如果较重的端点——完整 XBRL 财务数据、筛选器、OHLCV 柱——返回的数据超过此上限，服务会裁剪最大的数组，并附上 _truncated 说明，解释如何缩小查询范围。

实时 WebSocket 流式传输

流式传输比较特殊：它无法很好地适配单次请求/响应。因此，服务会保持一个持久 WebSocket 连接，将收到的数据帧缓存在缓冲区中，而各工具只需读取该缓冲区。频道（product 字段）包括 cex（加密货币）、dex（DEX 交易）、fx（外汇）、us（美国股票）和 tvl（DEX 池 TVL）。

有两种使用方式：

• 订阅 + 轮询，适用于持续数据流：调用一次 ws_subscribe，然后持续调用 ws_poll。首次轮询会返回最近的数据；将返回的 next_seq 作为 after_seq 传回后，就只会收到此后的新数据帧。ws_status 会显示连接状态和订阅内容，而 ws_disconnect 会关闭整个连接。
• 收集，适用于快速单次获取：ws_collect 会订阅并等待最多 duration_ms（或直到收到 max 个数据帧），返回捕获到的数据，并清理它为此创建的任何订阅。非常适合“帮我抓取几秒钟的 BTCUSD 数据”。

连接会自动重连，并在重连后恢复订阅。缓冲区采用滚动窗口，因此最早的数据帧最终会被移除；发生这种情况时，你会通过 dropped/gap 得知。

提示词

这些是客户端可以作为斜杠命令展示的多工具引导式工作流：

• company_snapshot (ticker) — 同时调用 stocks_profile、stocks_ratios、最新的 stocks_filings 和 last_trade，汇总成一份简报。
• compare_companies (tickers) — 并排列出多个股票代码，对比关键比率。
• market_now — 查看当前开盘和休市的市场，以及即将发生的重要宏观事件。

日志记录与关闭

服务器声明支持 MCP 日志记录能力，并在连接发生任何变化（WebSocket 打开／关闭／重新连接／出错）或服务器关闭时，向客户端推送结构化的 notifications/message，同时也会将所有这些信息输出到 stderr。

捕获到 SIGINT 或 SIGTERM 时，服务器会关闭活动的 WebSocket，并在退出前正常关闭。