PolyOrderbooks MCP Server

面向 Claude、Cursor 以及任何其他 MCP 客户端的 Polymarket 历史订单簿深度——以 1 秒分辨率提供完整的 L2 买盘与卖盘档位，并附带已结算的结果。

Polymarket 自身的 API 能很好地提供价格历史。但其不会以任何粒度归档订单簿深度——/book 只返回当前状态，无人保存。本服务器提供的数据是实时采集的深度信息，也就是事后无法再次恢复的那部分。

安装

无需安装。把它添加到你的 MCP 客户端配置中，即可通过 npx 运行。

Claude Desktop —— claude_desktop_config.json:

{
  "mcpServers": {
    "polyorderbooks": {
      "command": "npx",
      "args": ["-y", "@polyorderbooks/mcp-server"],
      "env": { "POLYORDERBOOKS_API_KEY": "pob_..." }
    }
  }
}

Cursor —— .cursor/mcp.json，格式相同。

修改配置后请重启客户端；MCP 服务器是在启动时启动的。

Related MCP server: polymarket-mcp-server

获取 API 密钥

1. 在 polyorderbooks.com/signup 注册。无需绑定银行卡。

2. 打开仪表盘并创建一个密钥。它的形式是 pob_ 后面跟一长串随机字符。

3. 把它放进 MCP 客户端配置的 env 块中，如上所示。

免费版 Starter 计划即可按 1 秒分辨率查询——与付费计划相同。付费计划提供的是更长的时间窗口和更高的请求配额，而不是更细的数据。在你决定是否付费之前，Starter 计划已足够回答实际问题。

你可以随时调用 get_usage 工具，查看已配置密钥对应的计划、限制和剩余配额。

环境变量

请将这些变量设置在 MCP 客户端配置中，不要放在你的 shell 里。客户端会以子进程方式启动服务器，不会将你的交互式 shell 环境传递给它，因此在 .zshrc 中导出的密钥对服务器是不可见的。

工具

整个目录结构是 series → events → markets。先用 search_series 查找某一类市场，再用 search_events 查找一同结算的一组市场，最后用 search_markets 查找具体市场。

解读数据前，你需要知道这些

订单簿会随着市场结算而变为单边。 在一个 5 分钟市场的最后一分钟内，76% 的快照会出现买盘或卖盘为空——没有人愿意为失败的结果挂单。这是真实的市场行为，不是数据缺失，也会导致那些假设双边订单簿的分析失效。

合约时长改变一切。 4 小时合约在 0.5% 的时间是单边；5 分钟合约则是 17%。从一个合约得出的结论无法迁移到另一个合约。

响应会很快变得很大。 以 1 秒分辨率记录 1 小时，每个结果代币会产生 3,600 个数据桶，而每个市场有 2 个结果代币。因此请把时间窗口缩小或把分辨率调粗，并使用返回的 next_cursor 分页。

示例提示词

查找昨天已结算的 BTC 5 分钟市场，并展示结算前最后两分钟订单簿深度是如何变化的。

对于这个市场，在收盘前 5 秒钟，按照实际档位买入 100 股需要花费多少？对比当时的中点价是更高还是更低？

对比 5 分钟、15 分钟和 4 小时 BTC 合约在过去一天的价差和流动性。

第二个提示是 L2 数据的价值所在。价格序列告诉你市场当时在哪里；只有档位能告诉你当时实际可以成交的价格。

与其他 Polymarket MCP 服务器的区别

市场已有几个不错的实现——kukapay/polymarket-predictions-mcp、demwick/polymarket-agent-mcp、PaulieB14/graph-polymarket-mcp。它们对 Polymarket 自己的 Gamma 和 CLOB API 进行了很好的包装。

这种差异是结构性的，而非取舍。Polymarket 的 /book 端点只返回当前状态，没有人对它进行归档，因此任何基于该 API 构建的服务器都无法提供过去的档位。本服务器读取的是当时实时捕获的归档数据。

如果你要交易或需要实时赔率，请使用他们的服务器——他们在这方面更出色。当问题是“某个过去时刻的盘口是什么样的”时，再使用本服务器。

故障排查

“POLYORDERBOOKS_API_KEY is not set” —— 密钥缺失。它应放在客户端配置的 env 块中，而不是放在你的 shell 里。请参阅 环境变量。

身份验证失败 —— 密钥已经传送到服务器，但 API 拒绝了它。密钥以 pob_ 开头；如果是从终端粘贴的，请检查是否为末尾新增了空格或引号。若密钥本身正确，调用 get_usage 确认密钥是否仍然有效。

响应被截断还很慢 —— 1 小时按 1 秒分辨率就是每个结果代币 3,600 个数据桶，而一个市场有两个代币。可以缩小时间窗口，或使用 resolution: "1m"，并用 next_cursor 分页。

空档位 —— 在临近结算时出现是正常的。感谢上面关于单边订单簿的说明。

开放数据

897,192 个快照覆盖 805 个已结算市场和三种合约期限，以 CC BY 4.0 协议发布并附 DOI，无需注册即可访问：

doi.org/10.5281/zenodo.22084114

适合你在决定依赖 API 之前，自行验证上述结论。

开发

npm install
npm run build
POLYORDERBOOKS_API_KEY=pob_... npm run dev

该服务器使用 stdio 通信。要在不使用 MCP 客户端的情况下 test 它，可以通过 stdin 发送 JSON-RPC 消息——先是 initialize，然后是 tools/list，最后是 tools/call。

链接

• polyorderbooks.com —— API

• docs.polyorderbooks.com —— 参考文档

• Python 客户端 —— pip install polyorderbooks

• 免费 BTC 样例 —— 一个市场，无需注册

许可证

MIT。本服务器与 Polymarket 无任何关联、无权提出自己有额外的 SOURCE 全覆盖托管的说法。