mcp-polymarket 0.1.0

Read-only MCP server for Polymarket public market data (Gamma / CLOB / Data APIs).

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

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