caiovicentino/polymarket-mcp-server

🤖 AI-Powered MCP Server for Polymarket - Enable Claude to trade prediction markets with 45 tools, real-time monitoring, and enterprise-grade safety features

🤖 Polymarket MCP Server – AI‑augmented trading for Polymarket

What it is – A Python‑based server that implements the Model Context Protocol (MCP) so that Anthropic’s Claude can interact with Polymarket prediction‑market APIs. It exposes 45 ready‑to‑use “tools” (functions) that let Claude (or any MCP‑compatible agent) discover markets, analyse order‑books, place and manage trades, and monitor a portfolio in real time.

Why it matters – Prediction‑market trading is a niche but growing arena for autonomous agents. By wrapping Polymarket’s CLOB, Gamma, and WebSocket endpoints behind a safety‑first MCP server, the project lets large‑language‑model agents act as semi‑autonomous traders while enforcing configurable risk limits.

Core capabilities (grouped into the five tool categories)

Category	Tools	What you can do
Market Discovery (8)	keyword search, trending lists, category filters, closing‑soon alerts, sport & crypto market browsers	Quickly find markets that match a strategy or interest.
Market Analysis (10)	live price/spread, order‑book depth, liquidity & volume metrics, historical prices, AI‑generated BUY/SELL/HOLD signals, multi‑market comparison, top‑holder scans, risk scoring	Get data‑driven insight and a Claude‑generated recommendation for any market.
Trading (12)	limit & market orders (GTC, GTD, FOK, FAK), batch submission, AI‑suggested pricing, order‑status tracking, bulk cancel, natural‑language‑to‑strategy execution, position rebalancing with slippage protection	Place and manage trades programmatically or via natural‑language prompts.
Portfolio Management (8)	real‑time position view, realized/unrealized P&L, aggregate portfolio value, concentration & diversification risk analysis, on‑chain activity log, AI‑driven portfolio optimisation (conservative / balanced / aggressive)	Keep an up‑to‑date picture of exposure and let Claude suggest adjustments.
Real‑time Monitoring (7)	WebSocket price streams, order‑book depth streams, order‑status notifications, execution alerts, market‑resolution notices, subscription handling, auto‑reconnect with exponential back‑off	Stay informed instantly; the dashboard visualises these streams.

Safety & risk‑management layer

Configurable caps for order size, total exposure, per‑market position, minimum market liquidity, and maximum spread.
Pre‑trade validation and confirmation flow (large orders can require an explicit confirm=true).
Rate‑limiting via a token‑bucket algorithm that respects Polymarket’s API limits.
EIP‑712 signed orders and wallet‑based authentication (Polygon private key + address).

Production‑ready infrastructure

MCP server written in Python 3.10+, installable with pip install -e ..
Web dashboard (polymarket-web or ./start_web_dashboard.sh) on http://localhost:8080 for visual configuration, live stats, and market browsing.
No mocks – the test suite hits the real Polymarket APIs, giving confidence that the code works against production endpoints.
Full test coverage and CI‑ready scripts (pytest, coverage reports).

Getting started (quick‑start)

# Demo (read‑only) – no wallet needed
curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash

# Full install (trading) – creates a venv, installs deps, and runs Claude‑Desktop integration
./install.sh               # macOS / Linux
install.bat                # Windows

Edit .env – set DEMO_MODE=true for read‑only, or provide POLYGON_PRIVATE_KEY and POLYGON_ADDRESS for live trading. Adjust safety limits as needed.

How an agent uses it

Claude (or any MCP‑compatible LLM) sends a JSON‑RPC request to the server, invoking a tool name such as market_analysis or place_limit_order. The server returns structured data (prices, risk scores, order confirmations) which Claude can incorporate into its next reasoning step. This round‑trip enables natural‑language‑driven autonomous trading while the server enforces the safety policies defined in .env.

Who might use this

Researchers exploring AI‑driven prediction‑market strategies.
Quant teams building custom agents that need a reliable bridge to Polymarket.
Individual traders who want a Claude‑powered assistant for market discovery and risk‑aware execution.

License & community

MIT‑licensed – free for commercial or personal use.
Active community on GitHub Issues, Discussions, and Telegram (linked from the repo).
Contributing guide and a “roadmap” that lists upcoming CI/CD, back‑testing, multi‑wallet support, and richer AI analysis tools.

Bottom line

Polymarket MCP Server is a real, production‑grade bridge between Anthropic’s Claude (via the MCP protocol) and Polymarket’s prediction‑market ecosystem. It bundles a large toolbox, safety checks, and a web UI, making it one of the most complete open‑source stacks for autonomous AI trading on prediction markets today.