Skip to main content
Glama
sunnywlad

polymarket-book-mcp

by sunnywlad
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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-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.

Available Tools

5 tools
get_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
url_or_slugYesFull polymarket.com market URL, or the bare market slug.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the transparency burden. It lists the returned fields (question, condition_id, token ids, etc.), which is helpful, but it does not explicitly state the operation is read-only, nor does it describe error behavior, response format, or side effects. Some behavioral detail is present, but it lacks completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that effectively communicates the tool's purpose and output fields. It is front-loaded with the main action and resource, and every word contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and no output schema, the description provides a thorough enumeration of the resolved fields, giving the agent a clear expectation of the result. It could be improved by noting potential errors (like invalid or unknown slugs) or the format of the response, but the essential context is covered well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage for the single parameter, describing it as 'Full polymarket.com market URL, or the bare market slug.' The tool description essentially repeats this without adding new semantics like examples, format constraints, or edge cases. Baseline of 3 applies because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Resolve') and resource ('polymarket.com market URL or bare slug'), and enumerates the specific output fields. This makes it unambiguous and distinct from sibling tools like search_markets or get_order_book.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when you already have a market URL or slug and need resolved metadata. However, it does not explicitly state when to prefer it over alternatives or provide any exclusion criteria. No alternative references are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNoNumber of price levels to return per side.
token_idYesCLOB token id for one specific outcome (not a condition_id, not a slug).

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It uses the verb 'Fetch', indicating a read-only operation, and details the output structure (levels, cumulative size, notional). It does not mention error conditions or permission requirements, but for a simple fetch this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences. The first front-loads the core behavior and output details; the second adds minor context about centrality. Both are concise and non-redundant. No unnecessary flourish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple two-parameter tool with no output schema or annotations, the description covers the essential behavior: return contents and the token scoping. Combined with the schema, this gives sufficient context for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions 'top N levels' which aligns with the depth parameter, and 'one outcome token' echoes the token_id description. No additional semantic value is provided beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a live order book for one outcome token, enumerating specific return elements (best bid/ask, mid, spread, top N levels). This distinguishes it from siblings like get_quote or get_price_history, which are not about order book depth.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that this is the order book tool and even calls itself 'the central tool of this server', implying it is the primary choice for order book data. It does not explicitly name alternatives or exclusions, but the context is sufficient for a typical use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_price_historyA

Historical price series for one outcome token, plus a small summary (count, first, last, min, max).

ParametersJSON Schema
NameRequiredDescriptionDefault
fidelityNoResolution in minutes between returned points.
intervalNoLookback window, e.g. '1h', '6h', '1d', '1w', '1m', 'max'.1d
token_idYesCLOB token id. Note: passed to the API's `market` parameter, which despite the name takes a token id.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It discloses that the tool returns a series plus a summary, which gives some insight into the output, but it does not explicitly mention read-only behavior, rate limits, or other potential side effects. The word 'get' implies a safe read operation, but the description alone does not fully cover transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that immediately conveys the core purpose and output structure. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple, with schema covering all parameters. The description provides a high-level summary of the return value (series + summary), which is sufficient for an agent to understand the tool's function. However, without an output schema, a bit more detail on the return format could be helpful, but it is not critical for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does not add significant detail beyond the schema; it mentions 'one outcome token' which maps to token_id, but does not enrich understanding of fidelity or interval.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as retrieving a historical price series for a single outcome token, including a summary of key statistics. This distinguishes it from sibling tools like get_quote (current price) and get_order_book (order book data).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies how to use the tool (for historical price data) but does not explicitly state when to choose it over alternatives or provide any exclusion criteria. The context is clear but there is no explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quoteA

Cheap price check for one outcome token: best_bid, best_ask, mid and spread only, no depth. One book fetch.

ParametersJSON Schema
NameRequiredDescriptionDefault
token_idYesCLOB token id for one specific outcome.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the tool is 'cheap' and performs 'one book fetch', indicating performance characteristics, and specifies exactly which fields are returned (best_bid, best_ask, mid, spread) and that there is no depth. It lacks details on error handling or auth, but for a simple quote tool this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficiently structured sentence that front-loads the purpose ('Cheap price check'), then specifies the token scope and available fields. Every phrase earns its place with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, no output schema), the description covers what it does, what it returns, and how it works ('one book fetch'). It also hints at its limitation (no depth), making it sufficient for tool selection even with sibling tools present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes token_id as 'CLOB token id for one specific outcome.' The description reinforces this with 'one outcome token' but adds no new syntax or format details. With 100% schema coverage, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs a 'cheap price check for one outcome token' with specific fields (best_bid, best_ask, mid, spread), distinguishing it from siblings like get_order_book which would provide depth.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context by saying 'no depth' and 'only', implying it's for quick checks when full order book depth is unnecessary. However, it does not explicitly name alternatives like get_order_book, so it offers a clear context with an implicit exclusion rather than explicit alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of markets to return.
queryYesFree-text search query.
include_closedNoInclude markets already closed/resolved.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the transparency burden. It discloses key behavioral details: it uses the site's real search backend, returns a flat list (flattening parent events), and includes specific fields (best bid/ask, spread, token IDs). It also warns about the no-op endpoint. Missing details like auth/rate limits are minor for a read-only search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose. The parenthetical about the no-op endpoint is useful and the output details are compact. Every sentence earns its place; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no output schema, and absence of annotations, the description is fairly complete: it explains what the tool does, why it is reliable (real backend), and what the return shape looks like. It could mention ordering or pagination, but the limit parameter partially covers that. It adequately supports selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema, mostly re-emphasizing keyword search. Limit and include_closed are not elaborated, but the schema handles them adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and resource ('Polymarket markets'), clearly distinguishing this from sibling tools that retrieve specific market data or order books. It also states the output ('flat list of markets with best bid/ask, spread and outcome/token ids'), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for keyword-based market discovery but does not explicitly state when to prefer this tool over alternatives like get_market or get_quote. It does mention a useful distinction (Gamma's own /markets?search= is a no-op) that guides usage, but no explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • polymarket-mcp

    pr1m8
    F
    license
    A
    quality
    B
    maintenance
    AI-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.
    22

  • polymarket-mcp

    fzlzjerry
    A
    license
    A
    quality
    B
    maintenance
    A 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.
    14
    MIT

  • hl-read

    akagifreeez
    A
    license
    Not graded
    quality
    B
    maintenance
    A read-only MCP server for Hyperliquid that provides public market data (prices, order books, funding) and any wallet's positions, orders, and fills via MCP tools, without requiring a private key.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunnywlad/polymarket-book-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server