SiftingIO MCP Server

siftingio-mcp (Python)

一个 Model Context Protocol（MCP）服务，可将 SiftingIO market-data SDK（siftingio）提供给你的 AI 助手使用。运行后，模型可以获取实时价格、读取 SEC/EDGAR 基本面数据、获取 OHLCV 数据条、查询 13F 持仓、检查市场状态，以及扫描宏观经济日历。

这是 siftingio-mcp（TypeScript 服务）的 Python 移植版，基于 FastMCP 构建。

设置

需要 Python 3.13+。

python -m venv .venv && source .venv/bin/activate
pip install -e .

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

export SIFTING_API_KEY=sft_...

如需使用其他后端，请通过 SIFTING_BASE_URL 和 SIFTING_WS_URL 覆盖默认值。

本地开发时，将 .env.example 复制为 .env，然后按你喜欢的方式加载（例如使用 set -a; . ./.env; set +a 或 direnv）。将其接入实际的 MCP 客户端时，请通过服务的 env 块传递密钥，而不是使用文件——下方有示例。

运行

命令：

• siftingio-mcp — 通过 stdio 运行服务（默认传输方式）。
• siftingio-mcp-http — 通过 Streamable HTTP 运行服务。
• python -m siftingio_mcp — 与 siftingio-mcp 相同，但不使用控制台脚本。
• pytest — 运行测试。
• ruff check / ruff format — 执行 lint 和格式化。
• mypy — 执行类型检查。

CI（.github/workflows/ci.yml）会在每次推送和 PR 时执行相同的步骤：格式检查、lint、类型检查、测试。

请注意，该服务通过 stdio 使用 JSON-RPC，因此 stdout 专用于协议。诊断信息会写入 stderr。

交互式检查

MCP inspector 是手动试用该服务最简单的方式：

SIFTING_API_KEY=sft_... npx @modelcontextprotocol/inspector siftingio-mcp

HTTP（Streamable HTTP）传输

对于远程或托管部署，请使用 MCP 的 Streamable HTTP 传输，而不是 stdio：

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

这是有状态的：每个客户端都有自己的会话（通过 mcp-session-id 标头跟踪），而上游 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_... siftingio-mcp-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": "siftingio-mcp",
      "env": { "SIFTING_API_KEY": "sft_..." }
    }
  }
}

如果客户端的 PATH 中没有 siftingio-mcp，请使用控制台脚本的绝对路径（/path/to/.venv/bin/siftingio-mcp）或 python -m siftingio_mcp。

工具

该服务公开了 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。

结果大小上限约为 6 万个字符（参见 siftingio_mcp/util.py 中的 MAX_RESULT_CHARS）。当大型端点——完整的 XBRL 财务数据、筛选结果、OHLCV K 线数据——返回的内容超过此上限时，服务会裁剪最大的数组，并添加 _truncated 说明，解释如何缩小查询范围。

**关于 from/to 的说明：**由于 from 是 Python 保留字，日期下界输入字段命名为 from_（与 SiftingIO SDK 自身的约定一致）。to 保持不变。

实时 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 — 查看当前开市和闭市的市场，以及即将发生的重大宏观事件。

日志记录与关闭

服务会将连接（WebSocket 打开/关闭/重新连接/错误）和关闭的结构化记录写入 stderr（stdout 保留用于 stdio 传输上的协议）。

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

许可证

MIT