PolyOrderbooks MCP Server

Historical Polymarket order book depth for Claude, Cursor and any other MCP client — full L2 bid and ask ladders at 1-second resolution, with resolved outcomes attached.

Polymarket's own API serves price history well. It does not archive order book depth at any granularity — /book returns the current state and nothing stores it. This server exposes depth that was captured live, which is the part that cannot be recovered after the fact.

Install

Nothing to install. Add it to your MCP client config and it runs via 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, same shape.

Restart the client after editing the config; MCP servers are started at launch.

Getting an API key

1. Sign up at polyorderbooks.com/signup. No card is required.
2. Open the dashboard and create a key. It looks like pob_ followed by a long random string.
3. Put it in the env block of your MCP client config, as above.

The free Starter plan queries at 1-second resolution — the same as the paid plans. What the paid plans add is a longer history window and a higher request allowance, not finer data. Starter is enough to answer a real question before you decide whether to pay for anything.

Call the get_usage tool at any time to see the plan, limits and remaining allowance on the key you configured.

Environment variables

Set these in the MCP client config, not in your shell. A client launches the server as a subprocess and does not pass your interactive shell environment to it, so a key exported in .zshrc will not be visible to the server.

Tools

The catalogue is series → events → markets. Ask for a kind of market with search_series, a set that resolves together with search_events, and a specific one with search_markets.

Things worth knowing before you interpret the data

Books go one-sided as markets resolve. In the final minute of a 5-minute market, 76% of snapshots have an empty bid or ask side — nobody offers the losing outcome. This is real market behaviour, not missing data, and it breaks analysis that assumes two-sided books.

Contract length changes everything. A 4-hour contract is one-sided 0.5% of the time; a 5-minute contract, 17%. Conclusions from one do not transfer to the other.

Responses get large quickly. An hour at 1-second resolution is 3,600 buckets per token, and a market has two. Keep windows narrow or resolution coarse, and page with the returned next_cursor.

Example prompts

Find BTC 5-minute markets that resolved yesterday and show me how the order book depth changed in the final two minutes before settlement.

For this market, what would a 100-share buy have cost against the actual ladder five seconds before close, versus the midpoint at that moment?

Compare spread and liquidity across 5-minute, 15-minute and 4-hour BTC contracts over the last day.

The second one is the point of L2 data. A price series tells you where the market was; only the ladder tells you what you could have traded at.

How this differs from other Polymarket MCP servers

Several good ones exist — kukapay/polymarket-predictions-mcp, demwick/polymarket-agent-mcp, PaulieB14/graph-polymarket-mcp. They wrap Polymarket's own Gamma and CLOB APIs and do it well.

The difference is structural rather than a matter of effort. Polymarket's /book endpoint returns the present state and nothing archives it, so no server built on that API can serve yesterday's ladders. This one reads an archive that was captured live.

If you want to trade, or want live odds, use one of theirs — they cover that better. Use this when the question is about what the book looked like at a specific past moment.

Troubleshooting

"POLYORDERBOOKS_API_KEY is not set" — the key is missing. It goes in the env block of the client config, not your shell. See Environment variables.

Authentication failed — the key reached the server but the API rejected it. Keys start with pob_; check for a trailing newline or a stray quote if you pasted from a terminal. If it looks right, call get_usage to confirm the key is active.

Responses truncated or slow — an hour at 1-second resolution is 3,600 buckets per token, and a market has two. Narrow the window, or use resolution: "1m" and page with next_cursor.

Empty ladders — expected near settlement. See the note above on one-sided books.

Open data

897,192 snapshots across 805 resolved markets and three contract lengths are published under CC BY 4.0 with a DOI, no signup:

doi.org/10.5281/zenodo.22084114

Useful for checking the properties above yourself before relying on the API.

Development

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

The server speaks stdio. To exercise it without an MCP client, send JSON-RPC on stdin — initialize, then tools/list, then tools/call.

Links

• polyorderbooks.com — the API
• docs.polyorderbooks.com — reference
• Python client — pip install polyorderbooks
• Free BTC sample — one market, no signup

Licence

MIT. Not affiliated with, endorsed by, or connected to Polymarket.