Polymarket MCP
MCP server that exposes read-only Polymarket prediction market data to AI agents. Tools wrap Polymarket's public Gamma (market discovery) and Data (positions, portfolio, leaderboard) APIs. There is no CLOB integration — this server cannot place trades or read order books.
<!-- mcp-name: io.github.0xChron/polymarket-mcp -->Tools
| Tool | Description |
|---|---|
search_markets | Search markets by title or description |
get_market_details | Full details for a single market (by slug or Polymarket URL) |
get_trending_markets | Trending events ranked by volume, liquidity, or competitiveness |
get_market_holders | Top holders per outcome for a market (by condition ID, slug, or URL) |
get_leaderboard | Top traders ranked by P&L or volume |
get_user_positions | Open positions for a wallet address |
get_user_performance | Portfolio value, P&L, volume, and leaderboard rank for one wallet |
All tools return markdown formatted for agent consumption. No API keys or wallet signing are required.
Resources
Static reference context (no API calls). Attach in MCP clients or read via Inspector.
| URI | Description |
|---|---|
polymarket://glossary | Event, market, slug, conditionId, and wallet terminology |
polymarket://categories | Leaderboard categories, time periods, and tag slugs |
polymarket://tool-guide | When to use each tool and chaining workflows |
Prompts
User-triggered workflow templates that orchestrate tools:
| Prompt | Description |
|---|---|
research_market | Market details → holders → research summary (slug or market_link) |
compare_traders | Side-by-side performance and positions for two wallets |
scan_trending | Trending events scan with optional tag_slug and limit |
Requirements
Quick start
This server uses streamable HTTP at http://127.0.0.1:8000/mcp. Start the server first, then connect your MCP client to that URL.
git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
uv sync
uv run polymarket-mcp
On Windows, use the same commands in PowerShell, Command Prompt, or Git Bash. Leave the terminal open while your MCP client is connected.
Docker
Works the same on all platforms if Docker Desktop is installed:
git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
docker build -t polymarket-mcp .
docker run --rm -p 8000:8000 -e FASTMCP_HOST=0.0.0.0 polymarket-mcp
FASTMCP_HOST=0.0.0.0 lets the server accept connections from outside the container.
Verify the server
Open MCP Inspector in another terminal:
npx -y @modelcontextprotocol/inspector
Connect to http://localhost:8000/mcp using the Streamable HTTP transport.
Connect from an MCP client
This server uses the streamable-http transport (not stdio). Start the server first (see Quick start), then add the config below to your MCP client.
Claude Desktop
Go to Claude → Settings → Developer → Edit Config to open claude_desktop_config.json, then include the following:
{
"mcpServers": {
"polymarket": {
"url": "http://localhost:8000/mcp"
}
}
}
If you already have other MCP servers configured, add the "polymarket" entry inside your existing mcpServers object instead of replacing the whole file.
Config file location if you prefer to edit it manually:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
Save the file and fully quit and restart Claude Desktop. The server must be running in a terminal before you start a new chat.
Cursor
Go to Settings → Tools & MCP → New MCP Server to open ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json), then add the same polymarket entry:
{
"mcpServers": {
"polymarket": {
"url": "http://localhost:8000/mcp"
}
}
}
Restart Cursor after saving.
Example agent prompts
Once connected, an agent can call tools naturally:
- "Search Polymarket for active markets about Bitcoin ETFs"
- "What are the trending markets right now?"
- "Who are the top holders of the Trump election market?"
- "Show the all-time P&L leaderboard for crypto traders"
- "Get details for https://polymarket.com/event/will-bitcoin-hit-100k"
- "Show open positions for wallet
0x…" - "What is the all-time P&L and leaderboard rank for
0x…?"
In MCP Inspector, try the Prompts tab (e.g. research_market) or read Resources for the glossary and tool guide.
Configuration
Optional environment variables override API endpoints and server settings.
macOS / Linux / Git Bash
export FASTMCP_HOST=0.0.0.0
export FASTMCP_PORT=8000
uv run polymarket-mcp
Windows (PowerShell)
$env:FASTMCP_HOST = "0.0.0.0"
$env:FASTMCP_PORT = "8000"
uv run polymarket-mcp
| Variable | Default | Description |
|---|---|---|
GAMMA_URL | https://gamma-api.polymarket.com | Gamma API base URL |
DATA_URL | https://data-api.polymarket.com | Data API base URL |
DEFAULT_TIMEOUT | 15 | HTTP request timeout (seconds) |
FASTMCP_HOST | 127.0.0.1 | Bind address (0.0.0.0 for Docker) |
FASTMCP_PORT | 8000 | Listen port |
Development
uv run polymarket-mcp # Start the server
uv run pytest # Run tests
npx -y @modelcontextprotocol/inspector # Open MCP Inspector
docker build -t polymarket-mcp . # Build Docker image
On macOS/Linux, make run, make test, and similar shortcuts in the Makefile wrap the same commands.
See docs/PROJECT_KNOWLEDGE_BASE.md for architecture, conventions, and how to add new tools.
License
MIT — see LICENSE.