Live Polymarket prediction-market data, exposed as MCP tools for Claude / Cursor / Cline.
A Model Context Protocol server that lets any MCP-compatible AI agent query live Polymarket markets natively — list markets by volume, pull historical price snapshots, find recent crashes (mean-reversion candidates), and inspect order-book depth, all without writing custom HTTP code in your prompts.
Backed by api.protodex.io — the LuciferForge Polymarket data layer indexing 9,500+ markets with a price snapshot every 15 minutes.
Why this exists: Polymarket has a public API but no MCP-native interface. Generic LLM tools can search the web for stale wiki entries; this gives your agent live, structured prediction-market data with crash signals it can reason over directly.
Seven tools, all read-only, all returning structured JSON the agent can consume:
| Tool | What it does |
|---|---|
get_stats |
Dataset-wide counts and freshness timestamps |
list_markets |
Paginated market list with category, search, sort filters |
get_market |
Single market detail with outcomes and CLOB token ids |
get_prices |
Historical price snapshots for a Yes/No outcome |
get_crashes |
Markets that dropped >= N% in the last H hours (default 15% / 4h) |
get_categories |
Category breakdown with market counts and volume |
get_orderbook |
Live bid/ask depth for a CLOB token id |
Coming in v0.2: WebSocket crash subscription bridged into the MCP transport.
If you have uv (every modern MCP client setup does):
uvx --from polymarket-mcp-pro polymarket-mcpThen point your client at uvx --from polymarket-mcp-pro polymarket-mcp. Done — no virtualenv to manage, always pulls the latest version.
pip install polymarket-mcp-pro
polymarket-mcp --helpNote: PyPI distribution name is
polymarket-mcp-pro(the barepolymarket-mcpname was already taken by an unrelated package). The CLI command and Python module both staypolymarket_mcp.
git clone https://github.com/LuciferForge/polymarket-mcp.git
cd polymarket-mcp
pip install -e .
polymarket-mcp --list-toolsEdit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:
{
"mcpServers": {
"polymarket": {
"command": "uvx",
"args": ["polymarket-mcp"],
"env": {
"POLYMARKET_API_KEY": ""
}
}
}
}Restart Claude Desktop. The polymarket tools will appear in the tool picker.
A drop-in copy of this snippet lives at examples/claude_desktop_config.json.
In Cursor settings -> Features -> MCP Servers, add:
{
"mcpServers": {
"polymarket": {
"command": "uvx",
"args": ["polymarket-mcp"],
"env": {
"POLYMARKET_API_KEY": ""
}
}
}
}A drop-in copy lives at examples/cursor_config.json.
Any client that speaks MCP stdio transport works. Use the same command (uvx --from polymarket-mcp-pro polymarket-mcp) and env block.
These are sample prompts you can paste into the AI agent. The agent will pick the right tool automatically — these are illustrative, not the literal API surface.
"Use polymarket get_crashes to show me politics markets that dropped at least 20% in the last 6 hours, ordered by largest drop."
The agent calls get_crashes(threshold=0.20, hours=6, category="politics") and gets back a list of markets with current price, recent high, and percent drop.
"List the top 5 crypto markets by 24-hour volume on Polymarket, then fetch the last 200 price snapshots for the highest-volume one."
The agent chains list_markets(category="crypto", sort="volume_24h", limit=5) -> get_prices(market_id, outcome="Yes", limit=200) and can plot, summarize, or feed the series into another tool.
"Get the Polymarket market for
0x1234...and show me the live orderbook for the Yes outcome."
The agent calls get_market(market_id), reads the outcomes_detail[].clob_token_id for the Yes outcome, then calls get_orderbook(token_id) to inspect the live book.
api.protodex.io is free for light usage and paid for production volume.
| Tier | Limit | How to get it |
|---|---|---|
| Free | 100 requests/day | No key required. Just install. |
| Sample | 1-day full dataset | $1 one-time -- Gumroad |
| Standard | 10,000 requests/day, 30 days | $9 one-time -- Gumroad |
| Cross-signal | 30,000 requests/day, 30 days | $29 one-time -- Gumroad |
After purchase, email LuciferForge@proton.me with your Gumroad purchase id and you'll receive an API key. Set it via the POLYMARKET_API_KEY env var in your MCP client config.
Storefront: https://manja8.gumroad.com.
Self-serve key issuance is on the roadmap.
| Variable | Default | Purpose |
|---|---|---|
POLYMARKET_API_KEY |
(unset) | Pro tier key. Without it you get the free 100/day tier. |
POLYMARKET_API_BASE |
https://api.protodex.io |
Override the API base (e.g. for self-hosting). |
POLYMARKET_API_TIMEOUT |
20 |
HTTP timeout in seconds. |
api.protodex.io-- the underlying free API this server wraps.- LuciferForge/polymarket-crash-bot -- the live mean-reversion trading bot (308 trades, 80.2% WR).
pip install pnl-truthteller-- audit your bot's actual on-chain P&L vs DB-recorded P&L. Wallet address only, no API key.pip install cross-signal-data-- 308-trade labeled crash-recovery dataset. Free, MIT, also on HuggingFace.pip install quant-rollout-- staged-deployment toolkit (gates, kill switch, veto window) for any trading bot.pip install sigil-ta-- MCP-native TA runtime with the unique Polymarket Sentiment Divergence signal.- LuciferForge/polymarket-v2-migration -- cookbook for the April 28, 2026 V1→V2 cutover.
- LuciferForge/polymarket-historical-data -- the historical Polymarket dataset (CSV / Parquet).
These three sit on the same data layer, so anything you can query through this MCP server is exactly what the bot trades on.
git clone https://github.com/LuciferForge/polymarket-mcp.git
cd polymarket-mcp
pip install -e ".[dev]"
pytest -q
polymarket-mcp --list-toolsRun the server in HTTP transport mode for manual testing:
polymarket-mcp --transport http --port 8765MIT. See LICENSE.
LuciferForge -- builds the Polymarket data layer at api.protodex.io and runs protodex.io, the largest MCP server directory (5,800+ servers indexed).