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

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