Polymarket MCP Server — Historical L2 Order Books

Overview & FAQ: See Polymarket MCP server for a fuller overview, common questions, and links to npm and Glama.

The PolyOrderbooks MCP server exposes our historical archive — full L2 bid/ask ladders at 1-second resolution. Polymarket’s own API does not store order book depth over time; this server reads what we captured live.

Prerequisites

A PolyOrderbooks account and API key (pob_…)
An MCP-capable client (Cursor, Claude Desktop, or custom)

Install

Add the server to your MCP client config. No global install — the client runs npx at launch. Cursor — .cursor/mcp.json:

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

Claude Desktop — claude_desktop_config.json uses the same shape. Restart the client after editing the config. MCP servers start at launch, not on first tool call.

Set POLYORDERBOOKS_API_KEY in the MCP config env block — not in your shell profile. The subprocess does not inherit your interactive shell environment.

Package: @polyorderbooks/mcp-server on npm

Tools

Tool	Purpose
`search_series`	Recurring market families (e.g. `btc-up-or-down-5m`)
`search_events`	Event groups that resolve together
`search_markets`	Keyword or date-range discovery
`get_market`	One market with outcome tokens and winner
`get_order_book_history`	L2 ladders over time — not on Polymarket API
`get_price_history`	Per-outcome price series
`get_market_metrics`	Spread, liquidity, volume time series
`get_usage`	Plan, rate limits, remaining quota

Discovery follows series → events → markets. Use get_usage anytime to check plan limits on the configured key.

Plans and resolution

The free Starter plan queries at 1-second resolution — the same granularity as paid tiers. Paid plans add a longer history window and higher rate limits, not finer data. See Pricing and Rate limits.

Example prompts

Find BTC 5-minute markets that resolved yesterday and show order book depth 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?

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

Keep time windows narrow at 1s resolution — responses grow quickly. Page with next_cursor when the tool returns it.

REST API alternative

Prefer HTTP directly? Start with Quickstart and Historical overview, or use the Python SDK.

Getting started

Discovery

Historical

Reference

Polymarket MCP Server — Historical L2 Order Books

Prerequisites

Install

Tools

Plans and resolution

Example prompts

REST API alternative

​Prerequisites

​Install

​Tools

​Plans and resolution

​Example prompts

​REST API alternative

Prerequisites

Install

Tools

Plans and resolution

Example prompts

REST API alternative