polymarket-book-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@polymarket-book-mcp Can you pull the order book for the 'Will Bitcoin reach $100k by 2025?' market?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: polymarket-mcp
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-mcpTools
Tool | Parameters | Description |
|
| Keyword search via Polymarket's real search backend. Results are interleaved across matching events, so a query like |
|
| 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. |
|
| Resolve a market URL or slug into its question, condition_id, per-outcome token ids, tick size, LP reward band, and status flags. |
|
| Cheap price check: best_bid, best_ask, mid, spread only. |
|
| 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 (backssearch_markets).GET https://gamma-api.polymarket.com/markets?slug=...— slug to conditionId (backsget_market).GET https://clob.polymarket.com/book?token_id=...— live order book (backsget_order_book,get_quote).GET https://clob.polymarket.com/markets/{condition_id}— market/token metadata (backsget_market).GET https://clob.polymarket.com/prices-history?market=...— historical prices (backsget_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:
clobTokenIdsandoutcomesare 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.mapor iterates on it directly will throw or silently do nothing. It needs ajson.loadsfirst, with a fallback for malformed or missing values.GET /markets?search=...is a no-op. It silently ignores thesearchparameter and returns an unrelated page of markets. The only endpoint that actually implements search isGET /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 /bookreturns bothbidsandasksin ascending price order. For asks that puts the best price (lowest ask) first, which looks correct and invites indexingasks[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=activedoes not fully filter./public-searchstill returns closed markets when asked for active ones, so the market's ownclosedflag has to be re-checked client-side.One-sided books are normal, not errors. Illiquid, closed, or resolving markets routinely return an empty
bidsorasksarray 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-historytakes a token id in a parameter namedmarket. 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.
Available Tools
5 toolsget_marketA
Resolve a polymarket.com market URL or bare slug into its question, condition_id, per-outcome token ids, tick size, LP reward band, and active/closed/accepting_orders status.
Inputs: url_or_slug (required).
get_order_bookA
Fetch the live order book for one outcome token: best bid/ask, mid, spread, and the top N levels per side with cumulative size and notional. This is the central tool of this server.
Inputs: token_id (required), depth.
get_price_historyA
Historical price series for one outcome token, plus a small summary (count, first, last, min, max).
Inputs: token_id (required), fidelity, interval.
get_quoteA
Cheap price check for one outcome token: best_bid, best_ask, mid and spread only, no depth. One book fetch.
Inputs: token_id (required).
search_marketsA
Search Polymarket markets by keyword via the site's real search backend (Gamma's own /markets?search= is a no-op and ignores the query). Returns a flat list of markets with best bid/ask, spread and outcome/token ids, flattened out of their parent events.
Inputs: query (required), limit, include_closed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Tools are mostly distinct: search_markets finds markets, get_market resolves a specific market, get_order_book provides full depth, get_quote provides a quick price snapshot, and get_price_history gives historical data. The only potential overlap is get_quote versus get_order_book, but the descriptions clearly differentiate a lightweight price check from full depth.
All tool names follow a consistent verb_noun pattern with lowercase and underscores: search_markets, get_market, get_order_book, get_quote, get_price_history. This is highly predictable and maintains a uniform style throughout.
Five tools is a well-scoped set for a market data server, covering search, resolution, current pricing (both depth and quick quote), and historical data. Each tool earns its place without unnecessary redundancy or bloat.
The server covers the core market data lifecycle: discovering markets, resolving identifiers, retrieving current order book depth, getting quick quotes, and accessing price history. Minor gaps like trade history or volume data exist, but the set is adequate for the stated purpose of a book-focused MCP.
Related MCP Connectors
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Read-only Polymarket search, market details, order books, price history, and market cards.
Read-only market data: tokens, stocks, Hyperliquid perps, Polymarket, and public trader books.
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Related MCP Servers
- FlicenseAqualityCmaintenanceAI-agent ready FastMCP server for Polymarket market discovery, wallet analytics, and public CLOB data, providing a read-only interface for querying markets, wallets, and order books.2235 PyPI-
- AlicenseAqualityCmaintenanceA read-only MCP server exposing Polymarket's public prediction-market data. Search markets, read live odds and order books, pull historical probability time-series, and inspect public wallet positions.1446 PyPIMIT
- AlicenseBqualityCmaintenanceMCP server for Polymarket prediction markets enabling query of markets, events, narratives, arbitrage, and more via MCP or HTTP.91MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server for Polymarket prediction market data, enabling AI agents to search markets, get details, view holders, leaderboard, and user positions.49 PyPIMIT