{
  "markdown": "# Polymarket MCP\n\n[![CI](https://github.com/beejmaxx/polymarket-mcp-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/beejmaxx/polymarket-mcp-rs/actions/workflows/ci.yml)\n[![Production API canary](https://github.com/beejmaxx/polymarket-mcp-rs/actions/workflows/live-canary.yml/badge.svg)](https://github.com/beejmaxx/polymarket-mcp-rs/actions/workflows/live-canary.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA 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.\n\nThe 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.\n\n## Install in a minute\n\nmacOS or Linux:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/beejmaxx/polymarket-mcp-rs/main/scripts/install.sh | sh\npolymarket-mcp-rs doctor\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/beejmaxx/polymarket-mcp-rs/main/scripts/install.ps1 | iex\npolymarket-mcp-rs doctor\n```\n\nOr use a package manager:\n\n```bash\nbrew install beejmaxx/tap/polymarket-mcp-rs\n```\n\n```powershell\nscoop bucket add beejmaxx https://github.com/beejmaxx/scoop-bucket\nscoop install beejmaxx/polymarket-mcp-rs\n```\n\nThen add it to a client:\n\n```bash\ncodex mcp add polymarket -- polymarket-mcp-rs\n# or\nclaude mcp add polymarket -- polymarket-mcp-rs\n```\n\nPrebuilt binaries and a one-click `polymarket-mcp.mcpb` bundle are attached to every [GitHub release](https://github.com/beejmaxx/polymarket-mcp-rs/releases). See [the install guide](docs/INSTALL.md) for Claude Desktop, VS Code, source builds, custom database paths, and Windows details.\n\n## Why this server\n\n- 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.\n- 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.\n- Correct numeric boundaries: decimal financial values and 256-bit IDs stay strings across JSON, preventing floating-point and integer loss.\n- Stateful market research: Rust maintains reconstructed books and feed health internally instead of sending every tick to the model.\n- Honest replay: SQLite stores observations captured by this process, tracks dropped updates, and never presents them as complete exchange history.\n- Safe defaults: trading tools are absent by default; exposing them and enabling mutation are separate decisions.\n- 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.\n\n## A useful first prompt\n\n> 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.\n\nOther demo prompts are in [docs/DEMO.md](docs/DEMO.md).\n\n## Tool profiles\n\n| Profile | Tools | Intended use |\n|---|---:|---|\n| `chatgpt` | 11 | Compact stateless public research surface for hosted clients |\n| `core` | 20 | Public REST discovery, books, wallets, answer-ready analysis, and simulation |\n| `research` (default) | 30 | Core plus realtime watching and local recording/replay |\n| `trading` | 36 | Core plus authenticated account, user-event streaming, and trading operations |\n| `all` | 46 | Research and trading together |\n\nSelect 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.\n\nRun `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](docs/TOOLS.md) for the grouped reference.\n\n## Architecture\n\n```text\nMCP client (stdio or Streamable HTTP)\n        |\n        v\ntool profile + typed MCP schemas\n        |\n        v\nvalidation and stable output mapping\n   |              |                |                 |\nGamma/Data/    CLOB REST      realtime books      SQLite + trading\npublic APIs    exact books    WebSocket health    replay / audit\n```\n\nThe 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.\n\n## Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `POLYMARKET_TOOL_PROFILE` | `research` | `chatgpt`, `core`, `research`, `trading`, or `all` |\n| `POLYMARKET_MCP_DB` | OS application-data directory | SQLite recording and approval-audit database |\n| `POLYMARKET_WS_URL` | Production market WebSocket | Override the full WebSocket URL |\n| `POLYMARKET_WS_PROXY` | unset | Unauthenticated `socks5://host:port` WebSocket proxy |\n| `HTTPS_PROXY` / `HTTP_PROXY` | environment dependent | Proxy used by HTTP API clients |\n| `RUST_LOG` | `info` | stderr log filtering |\n\nThe 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.\n\n## Trading is a separate opt-in\n\nRead [SECURITY.md](SECURITY.md) and [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) first. At minimum:\n\n```bash\nexport POLYMARKET_TOOL_PROFILE=all\nexport POLYMARKET_ENABLE_TRADING=true\nexport POLYMARKET_PRIVATE_KEY=0x...\nexport POLYMARKET_MAX_ORDER_PUSD=100\nexport POLYMARKET_SIGNATURE_TYPE=eoa\n```\n\nEOA, 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.\n\n## Development and evidence\n\nRust 1.90 or newer is required:\n\n```bash\ncargo fmt --check\ncargo clippy --locked --all-targets --all-features -- -D warnings\ncargo test --locked --all-features\ncargo test --locked --test live_api -- --ignored --nocapture\n```\n\nNormal 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.\n\nThe 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:\n\n```bash\npython3 scripts/parity_harness.py\n```\n\n- [Python replacement matrix](docs/PARITY.md)\n- [Migration from the Python server](docs/MIGRATING_FROM_PYTHON.md)\n- [Same-token Python comparison](docs/PYTHON_COMPARISON.md)\n- [Latest live parity audit summary](docs/PARITY_LIVE.md)\n- [ChatGPT setup](docs/CHATGPT.md)\n- [Read-only HTTP deployment](docs/DEPLOYMENT.md)\n- [Compatibility](docs/COMPATIBILITY.md)\n- [Contract stability](docs/STABILITY.md)\n- [Roadmap](docs/ROADMAP.md)\n- [Contributing](CONTRIBUTING.md)\n- [Privacy](PRIVACY.md)\n- [Support](SUPPORT.md)\n- [Launch and demo kit](docs/LAUNCH.md)\n\nThis software provides market infrastructure, not trading recommendations or financial advice.\n",
  "bytes": 8901,
  "sha": "c7a373047e6f3b2724c5337ac64aebdb0d5ff60f42b7c5e498c7a88463d4836c",
  "repo_slug": "beejmaxx/polymarket-mcp-rs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_beejmaxx_polymarket_mcp_b618dff0/readme"
}