polymarket-book-mcp

An MCP server that reads Polymarket order books, market metadata, and price history.

No private key, no trading, read-only. This package never imports py_clob_client, web3, or eth_account, never reads a wallet key, and never sends a POST or DELETE to any order endpoint. It only issues GET requests to Polymarket's public Gamma and CLOB APIs, the same endpoints the website itself uses to show you a book. There is no code path in here that could place, modify, or cancel an order, because the client that would do that was never written.

Why another one

A survey of existing Polymarket MCP servers turned up two patterns: some require a wallet private key to be configured just to read a public order book, which is a strange amount of trust to ask for a read-only operation; others expose market search or trade history but ship no order-book tool at all, which is the one piece of data a market-making or quoting workflow actually needs first. This package exists to fill that specific gap: order books, cleanly parsed, with no signing key anywhere in the dependency tree.

Install

uv venv
uv pip install -e .

Usage with Claude Code / Claude Desktop

Point the config at the venv's Python interpreter directly:

{"mcpServers": {"polymarket": {"type": "stdio",
  "command": "/absolute/path/to/polymarket-book-mcp/.venv/bin/python",
  "args": ["-m", "polymarket_book_mcp.server"]}}}

Or run it straight from GitHub with uvx, no local clone or install step:

uvx --from git+https://github.com/sunnywlad/polymarket-book-mcp polymarket-book-mcp

Tools

Tool	Parameters	Description
search_markets	query, limit=10, include_closed=False	Keyword search via Polymarket's real search backend. Results are interleaved across matching events, so a query like bitcoin returns several distinct events rather than one price ladder's worth of strikes.
get_order_book	token_id, depth=10	Live order book for one outcome token: best bid/ask, mid, spread, top N levels per side with cumulative size and notional. The central tool.
get_market	url_or_slug	Resolve a market URL or slug into its question, condition_id, per-outcome token ids, tick size, LP reward band, and status flags.
get_quote	token_id	Cheap price check: best_bid, best_ask, mid, spread only.
get_price_history	token_id, interval="1d", fidelity=60	Historical price series for one outcome token, plus a min/max/first/last summary.

Data sources

Every network call this server makes, so you can verify it yourself:

• GET https://gamma-api.polymarket.com/public-search — market/event search (backs search_markets).
• GET https://gamma-api.polymarket.com/markets?slug=... — slug to conditionId (backs get_market).
• GET https://clob.polymarket.com/book?token_id=... — live order book (backs get_order_book, get_quote).
• GET https://clob.polymarket.com/markets/{condition_id} — market/token metadata (backs get_market).
• GET https://clob.polymarket.com/prices-history?market=... — historical prices (backs get_price_history).

Both APIs are public and require no authentication for these read paths.

Notes on the Polymarket API

A few behaviors worth knowing if you're building on these endpoints yourself, each reproduced directly against the live API:

• clobTokenIds and outcomes are JSON-encoded strings, not arrays. A Gamma market object contains "clobTokenIds": "[\"5144...\", \"6848...\"]", a string that happens to look like a JSON array, not an actual array. Code that calls .map or iterates on it directly will throw or silently do nothing. It needs a json.loads first, with a fallback for malformed or missing values.
• GET /markets?search=... is a no-op. It silently ignores the search parameter and returns an unrelated page of markets. The only endpoint that actually implements search is GET /public-search?q=..., the one behind the website's search box.
• The order book's price levels are not sorted the way you'd expect. GET /book returns both bids and asks in ascending price order. For asks that puts the best price (lowest ask) first, which looks correct and invites indexing asks[0]. For bids, ascending order puts the best price (highest bid) last: bids[0] is the worst bid in the book, not the touch. Both sides need an explicit sort before you can trust [0].
• events_status=active does not fully filter. /public-search still returns closed markets when asked for active ones, so the market's own closed flag has to be re-checked client-side.
• One-sided books are normal, not errors. Illiquid, closed, or resolving markets routinely return an empty bids or asks array with HTTP 200. Best bid, best ask, mid, and spread all have to degrade to null rather than raising, and mid/spread need both sides to mean anything.
• /prices-history takes a token id in a parameter named market. Passing an actual condition_id there returns an empty history with no error, which reads like a market with no trading rather than a bad call.

Note on the MCP Python SDK version

The mcp dependency is pinned >=1.9,<2 deliberately. SDK 2.0.0 removed the Server.list_tools decorator, so any server written against the 1.x low-level API dies at startup with AttributeError: 'Server' object has no attribute 'list_tools'. If you are debugging that error in another MCP server, an unbounded mcp>=1.0.0 pin in its dependencies is very likely the cause.