Skip to main content
Glama
Sign In
polymarket-mcp

polymarket-mcp

by fzlzjerry
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Polymarket MCP Server (read-only)

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 — all over public, unauthenticated endpoints.

Read-only by design. No order placement, cancellation, signing, wallets, or private keys. No API keys, no environment variables, zero secrets.

Tools

Tool

What it does

polymarket_search

Natural-language search across events / markets / tags.

polymarket_list_markets

Browse & filter markets (volume, liquidity, dates, tags).

polymarket_get_market

Full detail for one market by id, slug, or condition_id.

polymarket_list_events

Browse & filter events (groups of markets).

polymarket_get_event

Event detail with all child markets.

polymarket_trending_markets

What's hot right now (top markets by 24h volume).

polymarket_get_live_price

Freshest CLOB midpoint / bid / ask / spread for an outcome token.

polymarket_get_order_book

Live order book (top N levels) for an outcome token.

polymarket_get_price_history

Historical probability time-series for an outcome token.

polymarket_get_user_positions

Public current holdings for a wallet.

polymarket_get_user_activity

Recent on-chain activity for a wallet.

polymarket_get_market_holders

Top holders per outcome token for a market.

polymarket_get_user_value

Total portfolio value (USDC) for a wallet.

polymarket_market_snapshot

Recommended: live odds for one market in a single call.

Every tool is annotated readOnlyHint=True, openWorldHint=True.

Key concepts

  • Prices are probabilities. Outcome prices are floats in [0, 1] (e.g. 0.41 = 41%). Tools also surface a human-readable probability_pct.

  • token_id vs conditionId. CLOB pricing/book/history tools key on a CLOB token id (one per outcome, from a market's clobTokenIds) — not a slug or conditionId. The Data API's condition_id identifies the market itself.

  • Freshness. Gamma discovery data can lag the live CLOB book by a few seconds. For the freshest odds use polymarket_get_live_price / polymarket_market_snapshot (CLOB midpoint).

Related MCP server: polyrouter-mcp

Install

Requires uv (Python 3.11+).

Published to PyPI as mcp-polymarket:

# Run on demand (no install):
uvx mcp-polymarket

# Or install as a persistent tool:
uv tool install mcp-polymarket

Registration

No environment variables or API keys are required.

Claude Code (CLI)

claude mcp add polymarket -- uvx mcp-polymarket

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "uvx",
      "args": ["mcp-polymarket"]
    }
  }
}

Development

From a checkout of this repo:

uv sync                              # install deps
uv run mcp-polymarket                # run the server (stdio)
uv run python tests/smoke_test.py    # live smoke test (hits the public API)

Inspect the tool schemas and annotations:

npx @modelcontextprotocol/inspector uvx mcp-polymarket

Publishing

Releases are published to PyPI automatically via Trusted Publishing — no API tokens are stored. The workflow in .github/workflows/publish.yml runs uv build and uploads the artifacts whenever a GitHub Release is published. To cut a release:

# bump `version` in pyproject.toml, commit, then:
gh release create v0.1.0 --generate-notes

Self-hosting over HTTP (optional)

In addition to the default stdio transport, the server can run over streamable-HTTP:

uv run polymarket-mcp --http --host 0.0.0.0 --port 8000
# served at http://<host>:<port>/mcp

Evaluation

evaluation.xml contains stable, verifiable, read-only questions exercising multi-tool workflows (search → market → price history → live price, etc.).

Available Tools

14 tools
polymarket_get_eventA
Read-only

Event detail with all child markets (parsed outcomes/prices/tokenIds).

Useful for multi-candidate / neg-risk events. Provide an id or a slug.

Inputs: id, slug. Returns: id, ticker, slug, title, +8 more

polymarket_get_live_priceA
Read-only

Freshest live odds for one outcome token from the CLOB.

token_id is a CLOB token id (one of a market's clobTokenIds) — NOT a slug or conditionId. Returns midpoint, best bid/ask, spread, and probability_pct. These are fresher than Gamma's cached prices.

Inputs: token_id (required). Returns: token_id, midpoint, best_bid, best_ask, +2 more

polymarket_get_marketA
Read-only

Resolve one market in full detail by id, slug, OR condition_id (provide one).

Args: id: Numeric Gamma market id (e.g. "507034"). A "0x..." value is treated as a condition id. slug: Market slug (e.g. "will-trump-win-the-2024-us-presidential-election"). condition_id: On-chain condition id ("0x...").

Inputs: id, slug, condition_id. Returns: id, question, slug, condition_id, +19 more

polymarket_get_market_holdersA
Read-only

Top holders per outcome token for a market.

Args: condition_id: The market's on-chain condition id ("0x..."). (Maps to the Data API's market param.) limit: Top-N holders per token, capped at 20 by the API.

Inputs: condition_id (required), limit. Returns: condition_id, tokens

polymarket_get_order_bookA
Read-only

Live order book for one outcome token: best bid/ask, midpoint, spread, top levels.

token_id is a CLOB token id. depth caps the number of price levels per side (default 10, max 50). Level prices/sizes are parsed to floats.

Inputs: token_id (required), depth. Returns: token_id, market_condition_id, best_bid, best_ask, +4 more

polymarket_get_price_historyA
Read-only

Historical probability time-series for one outcome token.

token_id is a CLOB token id (it maps to the misleadingly-named market param).

Args: interval: One of "1h", "6h", "1d", "1w", "1m" (1 month), "max", "all". Ignored when an explicit start_ts/end_ts range is given. fidelity: Resolution in minutes. Defaults to a safe value per interval (wider ranges require a higher minimum). start_ts/end_ts: Optional unix-second bounds (override interval).

Long series are downsampled to <=500 points (flagged in the result).

Inputs: token_id (required), interval, fidelity, start_ts, +1 more. Returns: token_id, interval, count, downsampled, +2 more

polymarket_get_user_activityA
Read-only

Recent on-chain activity (trades, splits, merges, redeems...) for a wallet.

Args: wallet: EVM address (0x...). limit: 1-100 (default 20). type: Optional activity type, e.g. "TRADE", "SPLIT", "MERGE", "REDEEM", "REWARD".

Inputs: wallet (required), limit, type. Returns: result

polymarket_get_user_positionsA
Read-only

Public current holdings for a wallet address (0x...).

Args: wallet: EVM address, e.g. "0x...". limit: 1-100 (default 20). sort_by: One of CURRENT, CASHPNL, PERCENTPNL, TOKENS, INITIAL, PRICE, AVGPRICE, TITLE, RESOLVING (default CURRENT). Sorted descending.

Inputs: wallet (required), limit, sort_by. Returns: result

polymarket_get_user_valueA
Read-only

Total current value (USDC) of a wallet's Polymarket positions.

Args: wallet: EVM address (0x...).

Inputs: wallet (required). Returns: user, value

polymarket_list_eventsA
Read-only

Browse and filter events (groups of related markets). Same shape as list_markets.

Note: events use volume_min/liquidity_min (NOT the _num_ infix that markets use).

Inputs: active, closed, tag_id, order, +9 more. Returns: result

polymarket_list_marketsA
Read-only

Browse and filter markets. Defaults to active, open markets by 24h volume.

Args: active: Best-effort active filter (Gamma honors it though it's under-documented). closed: Include resolved/closed markets (default False). tag_id: Single numeric tag id to filter by. order: Sort field, e.g. "volume24hr", "liquidity_num", "volume_num", "endDate". ascending: Sort ascending (default False = highest first). volume_num_min: Minimum total volume (note the _num_ infix for markets). liquidity_num_min: Minimum liquidity. start_date_min/start_date_max/end_date_min/end_date_max: ISO-8601 bounds. limit: 1-100 (default 20). offset: paging offset.

Inputs: active, closed, tag_id, order, +9 more. Returns: result

polymarket_market_snapshotA
Read-only

Live odds for one market in a single call (the recommended starting point).

Resolves a market (by slug, or by searching free text and picking the most liquid match), then fetches the freshest CLOB midpoint for each outcome token. Gamma's cached price can lag the live book — live_midpoint is the freshest value.

Provide a slug (preferred) or a free-text query.

Inputs: slug, query. Returns: question, slug, condition_id, volume24hr, +4 more

polymarket_searchA
Read-only

Natural-language search across Polymarket events, markets, and tags.

The primary entry point for "find me markets about X". Each returned event includes a short list of its markets with parsed outcomes and probabilities.

Args: query: Free text, e.g. "2024 election" or "bitcoin 100k". limit_per_type: Max results per type (events/tags), capped at 20. events_status: Optional status filter, e.g. "active". keep_closed_markets: Include closed markets in results (default False).

Inputs: query (required), limit_per_type, events_status, keep_closed_markets. Returns: events, tags, total_results

polymarket_trending_marketsA
Read-only

What's hot right now: active, open markets sorted by 24h volume (descending).

Inputs: limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct data item (event, market, order book, price history, user activity, etc.) with precise descriptions that show clear differences. No two tools overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent 'polymarket_verb_noun' pattern, e.g., get_event, list_markets, search. Verbs like get, list, search are used logically and uniformly.

    Tool Count5/5

    14 tools cover all major read operations for a prediction market: browsing, searching, detailed views, prices, order books, user data. This is well-scoped for the domain.

    Completeness5/5

    The tool set provides comprehensive coverage for querying Polymarket: event/market discovery, live prices, historical data, order books, and user positions/value. No obvious gaps for read-only access.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • polymarket-mcp

      pr1m8
      F
      license
      A
      quality
      C
      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

      amerilain
      A
      license
      B
      quality
      C
      maintenance
      MCP server for Polymarket prediction markets enabling query of markets, events, narratives, arbitrage, and more via MCP or HTTP.
      9
      MIT

    • graph-polymarket-mcp

      phon3
      A
      license
      B
      quality
      D
      maintenance
      MCP server to query Polymarket prediction market data via The Graph subgraphs and REST APIs, enabling AI agents to search markets, get live prices, order books, on-chain analytics, and trader profiles.
      32
      116 npm
      MIT