> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyorderbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket MCP Server — Historical L2 Order Books

> Install @polyorderbooks/mcp-server for Cursor, Claude Desktop, or any MCP client — query 1-second L2 order book history from chat.

<Note>
  **Overview & FAQ:** See [Polymarket MCP server](https://polyorderbooks.com/polymarket-mcp-server) for a fuller overview, common questions, and links to npm and Glama.
</Note>

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](https://polyorderbooks.com/signup) 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`:

```json theme={null}
{
  "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.

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

Package: [@polyorderbooks/mcp-server on npm](https://www.npmjs.com/package/@polyorderbooks/mcp-server)

## 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](/pricing) and [Rate limits](/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](/quickstart) and [Historical overview](/historical/overview), or use the [Python SDK](https://pypi.org/project/polyorderbooks/).