Polymarket MCP

Polymarket MCP

A self-contained Rust MCP server for Polymarket: source-linked market briefs, public discovery, exact CLOB V2 books, wallet analytics, realtime market state, SQLite recording/replay, fill simulation, and safely gated optional trading.

The default research profile needs no API key or wallet. It exposes 30 public/realtime tools and does not advertise or accept calls to authenticated trading tools. A separate 11-tool chatgpt profile is compact, stateless, credential-blind, and available over Streamable HTTP with an optional inline market card.

Install in a minute

macOS or Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/beejmaxx/polymarket-mcp-rs/main/scripts/install.sh | sh
polymarket-mcp-rs doctor

Windows PowerShell:

irm https://raw.githubusercontent.com/beejmaxx/polymarket-mcp-rs/main/scripts/install.ps1 | iex
polymarket-mcp-rs doctor

Or use a package manager:

brew install beejmaxx/tap/polymarket-mcp-rs

scoop bucket add beejmaxx https://github.com/beejmaxx/scoop-bucket
scoop install beejmaxx/polymarket-mcp-rs

Then add it to a client:

codex mcp add polymarket -- polymarket-mcp-rs
# or
claude mcp add polymarket -- polymarket-mcp-rs

Prebuilt binaries and a one-click polymarket-mcp.mcpb bundle are attached to every GitHub release. See the install guide for Claude Desktop, VS Code, source builds, custom database paths, and Windows details.

Why this server

• Verified replacement surface: 46 tools across public data, live books, research workflows, and opt-in account operations, with an automated live audit against all 25 Python demo tools.
• Answer-ready workflows: one market brief joins metadata, executable books, history, fill impact, source URLs, timestamps, and limitations; wallet and explicit negative-risk event summaries avoid unnecessary tool chains.
• Correct numeric boundaries: decimal financial values and 256-bit IDs stay strings across JSON, preventing floating-point and integer loss.
• Stateful market research: Rust maintains reconstructed books and feed health internally instead of sending every tick to the model.
• Honest replay: SQLite stores observations captured by this process, tracks dropped updates, and never presents them as complete exchange history.
• Safe defaults: trading tools are absent by default; exposing them and enabling mutation are separate decisions.
• Operationally simple: one binary, stdio or stateless Streamable HTTP, structured errors, health and Prometheus endpoints, an offline/online doctor, graceful shutdown, daily production canaries, containers, checksums, SBOMs, and release provenance.

A useful first prompt

Find the five highest-volume active Polymarket markets. For each, show the current outcome prices, liquidity, spread, order-book imbalance, and estimated slippage for 100 shares. Explain data limitations and do not recommend a trade.

Other demo prompts are in docs/DEMO.md.

Tool profiles

Profile	Tools	Intended use
chatgpt	11	Compact stateless public research surface for hosted clients
core	20	Public REST discovery, books, wallets, answer-ready analysis, and simulation
research (default)	30	Core plus realtime watching and local recording/replay
trading	36	Core plus authenticated account, user-event streaming, and trading operations
all	46	Research and trading together

Select a profile with --tool-profile research or POLYMARKET_TOOL_PROFILE=research. Hidden tools are removed from both tools/list and dispatch. Choosing trading or all only exposes the tool definitions; order mutation still requires POLYMARKET_ENABLE_TRADING=true, a signer, local caps, and per-operation confirmation. Public HTTP accepts only chatgpt or core and constructs an application instance that ignores credentials by design.

Run polymarket-mcp-rs tools to inspect the default catalog or polymarket-mcp-rs --tool-profile all tools --json for complete schemas. See docs/TOOLS.md for the grouped reference.

Architecture

MCP client (stdio or Streamable HTTP)
        |
        v
tool profile + typed MCP schemas
        |
        v
validation and stable output mapping
   |              |                |                 |
Gamma/Data/    CLOB REST      realtime books      SQLite + trading
public APIs    exact books    WebSocket health    replay / audit

The market WebSocket engine seeds each watched token from CLOB REST, then applies full snapshots and incremental price changes. Authenticated profiles can separately watch account order and trade events. Connection state, reconnects, source-specific counters, local receipt time, feed age, errors, and recording gaps remain explicit. SQLite writes use a bounded channel and dedicated writer thread; active recordings flush before watches stop on MCP EOF, SIGINT, or SIGTERM.

Configuration

Variable	Default	Purpose
POLYMARKET_TOOL_PROFILE	research	chatgpt, core, research, trading, or all
POLYMARKET_MCP_DB	OS application-data directory	SQLite recording and approval-audit database
POLYMARKET_WS_URL	Production market WebSocket	Override the full WebSocket URL
POLYMARKET_WS_PROXY	unset	Unauthenticated socks5://host:port WebSocket proxy
HTTPS_PROXY / HTTP_PROXY	environment dependent	Proxy used by HTTP API clients
RUST_LOG	info	stderr log filtering

The default database is in ~/Library/Application Support/polymarket-mcp/ on macOS, $XDG_DATA_HOME/polymarket-mcp/ (or ~/.local/share/polymarket-mcp/) on Linux, and %LOCALAPPDATA%\polymarket-mcp\ on Windows. ALL_PROXY=socks5://... is also honored for the public market WebSocket when POLYMARKET_WS_PROXY is unset; neither setting is needed on a normal unrestricted network. The server has no telemetry.

Trading is a separate opt-in

Read SECURITY.md and docs/THREAT_MODEL.md first. At minimum:

export POLYMARKET_TOOL_PROFILE=all
export POLYMARKET_ENABLE_TRADING=true
export POLYMARKET_PRIVATE_KEY=0x...
export POLYMARKET_MAX_ORDER_PUSD=100
export POLYMARKET_SIGNATURE_TYPE=eoa

EOA, legacy Proxy, Gnosis Safe, and POLY_1271 configurations are supported. preview_order performs policy and current-market-rule checks and creates a single-use five-minute approval. place_order consumes that approval and requires confirm=true; batch placement requires PLACE_BATCH. Cancellations have their own confirmations. Approval transitions are persisted before submission, and ambiguous network outcomes are never reported as safe retries. Account reads and user-event watches do not silently enable cancel-on-disconnect heartbeats.

Development and evidence

Rust 1.90 or newer is required:

cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features
cargo test --locked --test live_api -- --ignored --nocapture

Normal tests are offline and launch the compiled executable as a real stdio MCP subprocess. The ignored suite exercises current production Gamma, Data, CLOB REST, wallet, scanning, WebSocket, recording, replay, and simulation paths; it never places an order. Tool catalogs have committed golden contracts, and release tags rebuild on five OS/architecture targets.

The live semantic replacement audit launches both this server and the reference Python server through MCP, maps every Python demo tool, and fails on a Rust error or invariant violation:

python3 scripts/parity_harness.py

• Python replacement matrix
• Migration from the Python server
• Same-token Python comparison
• Latest live parity audit summary
• ChatGPT setup
• Read-only HTTP deployment
• Compatibility
• Contract stability
• Roadmap
• Contributing
• Privacy
• Support
• Launch and demo kit

This software provides market infrastructure, not trading recommendations or financial advice.