Read-only Polymarket prediction market data for AI agents.
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.
| 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.
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 |
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 |
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.
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.
Open MCP Inspector in another terminal:
npx -y @modelcontextprotocol/inspector
Connect to http://localhost:8000/mcp using the Streamable HTTP transport.
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.
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.
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.
Once connected, an agent can call tools naturally:
0x…"0x…?"In MCP Inspector, try the Prompts tab (e.g. research_market) or read Resources for the glossary and tool guide.
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 |
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.
MIT — see LICENSE.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx 0xchron-polymarket-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-0xchron-polymarket-mcp": {
"command": "uvx",
"args": [
"0xchron-polymarket-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceio.github.0xChron/polymarket-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.