Polymarket MCP Server

An MCP (Model Context Protocol) server that exposes read-only tools for querying live Polymarket prediction-market data via the public Gamma API. Built with FastMCP.

No API key required — the Gamma API is public and unauthenticated.

Tools

All tools are read-only (readOnlyHint: true).

get_active_markets sort keys

Known tag_slug values: politics, crypto, sports, elections, geopolitics. Omit for all categories.

Field coverage at a glance

Fields that require drilling down — search_markets returns less than the list/detail tools, and get_event returns less per-market than get_market:

Domain model & data conventions

The server sends these conventions to clients on connect as part of its instructions, but they're worth knowing upfront:

• Event vs. market. An event is a topic that groups one or more related markets (e.g. event Democratic Nominee 2028 groups per-candidate markets). A market is a single binary question with a share price in [0, 1] that reflects the crowd-estimated probability.
• `outcome_prices` and `outcomes` are JSON-encoded strings, not lists. Parse with json.loads, e.g. '["0.0135", "0.9865"]' → ["0.0135", "0.9865"]. For binary markets, index 0 is YES, index 1 is NO, and values sum to ~1.0. outcome_prices is null for untraded markets.
• Prices are probabilities, not dollars. best_bid, best_ask, last_trade_price, and the parsed entries of outcome_prices are all in [0, 1].
• USD units. volume, volume_24hr, liquidity are USD (float, may be null).
• Dates. end_date is ISO 8601 UTC (e.g. "2026-07-01T04:00:00Z") or null when an event's sub-markets have staggered dates.

Dependencies

Installation

Requires Python 3.10+.

With uv (recommended)

git clone https://github.com/jiroamato/polymarket_mcp.git
cd polymarket_mcp
uv sync

uv sync reads pyproject.toml and installs all dependencies into an isolated virtual environment automatically.

With pip

git clone https://github.com/jiroamato/polymarket_mcp.git
cd polymarket_mcp
pip install -e .

Installing the package also registers a polymarket-mcp console script (see pyproject.toml) that you can use as the command in any MCP client config.

Usage

There are three ways to wire this server into an MCP client, in increasing order of "how much JSON you touch".

Option A — FastMCP CLI install (easiest)

FastMCP ships install commands that write the client config for you.

Claude Code:

fastmcp install claude-code src/polymarket_mcp/server.py

Claude Desktop:

fastmcp install claude-desktop src/polymarket_mcp/server.py --server-name "Polymarket"

Useful flags: --python 3.11, --project /path/to/polymarket_mcp, --with httpx, --env KEY=VALUE, --env-file .env. See fastmcp install --help for the full list.

Option B — Direct Python

If you've already installed dependencies into a Python environment (via uv sync or pip install -e .), point the client directly at that interpreter.

Claude Code — add to your .claude.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/python",
      "args": [
        "/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/python",
      "args": [
        "/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Replace /path/to/python with the full path to your interpreter (e.g., C:/Users/you/miniforge3/python.exe, /Users/you/.venv/bin/python).

If you ran pip install -e ., you can instead use the installed console script:

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/polymarket-mcp"
    }
  }
}

Standalone:

python src/polymarket_mcp/server.py
# or, after `pip install -e .`:
polymarket-mcp

Option C — uv run (no pre-installed deps)

uv handles dependency isolation automatically — no need to install fastmcp or httpx yourself.

Claude Code:

claude mcp add polymarket -- uv run --with fastmcp --with httpx fastmcp run src/polymarket_mcp/server.py

Or add to your .claude.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with", "httpx",
        "fastmcp",
        "run",
        "/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
      ]
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with", "httpx",
        "fastmcp",
        "run",
        "/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
      ]
    }
  }
}

Standalone:

uv run fastmcp run src/polymarket_mcp/server.py

Example prompts

Once connected, try asking your AI assistant:

• "What are the top prediction markets on Polymarket right now?"
• "Search Polymarket for markets about AI."
• "Show me the most liquid crypto prediction markets."
• "Which politics markets on Polymarket are expiring soonest?"
• "Get details on Polymarket event 903 and summarize the candidates."
• "For Polymarket market 573655, what's the current spread and 1-day price change?"

Development

# Install dependencies
uv sync

# Run the server locally
uv run fastmcp run src/polymarket_mcp/server.py

# Inspect tools interactively with the MCP Inspector (browser UI)
uv run fastmcp dev inspector src/polymarket_mcp/server.py

The server itself lives in a single file: src/polymarket_mcp/server.py. Each tool is a plain function decorated with @mcp.tool(annotations={"readOnlyHint": True}); FastMCP generates the JSON schema from the type hints and docstring automatically.