Polymarket MCP Server: Giving Claude 45 Tools to Trade Prediction Markets

What Polymarket MCP Server actually solves

Polymarket exposes a CLOB API, and reaching it from a language model means writing a client, signing EIP-712 order payloads, handling token-bucket rate limits, and keeping a WebSocket alive through disconnects. This project packages that work as a Model Context Protocol server, so Claude Desktop and other MCP clients get 45 named tools instead of a blank HTTP surface. The audience is narrow and specific: someone with a Polygon wallet who wants an assistant to search markets, pull orderbook depth, compute spreads, place limit or market orders, and read back positions and P&L. The README splits those 45 tools across five groups (8 discovery, 10 analysis, 12 trading, 8 portfolio, 7 real-time), which tells you the project treats analysis as roughly as important as execution.

The honest framing is that this is a trading bridge with a chat interface on top, not an analytics toy. Anything the model can call, it can call with your credentials attached. That is the whole value proposition and also the whole risk surface, and the repository's own safety section reads like the author knows it.

How the server wires Claude to the Polymarket CLOB

The architecture is a Python process speaking MCP over stdio. The Dockerfile is explicit about this: it comments that MCP servers communicate via stdio, not HTTP ports, and the container entry point is python -m polymarket_mcp.server. Your MCP client launches that process and exchanges tool calls with it. Underneath, the server depends on py-clob-client for order construction and submission, eth-account for EIP-712 signing, and websockets for the real-time layer. The README describes L1 authentication as the wallet private key and L2 as API key credentials, with the API credentials auto-created on first run if you leave them empty.

Data flows in two directions. On request, a tool call goes out to the Polymarket REST API and the result comes back as a tool response the model can read. Separately, the WebSocket subscription pushes price updates, orderbook depth, order status and market resolution events; the README lists auto-reconnect with exponential backoff for that channel. Rate limiting uses a token bucket algorithm, according to the README, sized to the Polymarket API limits. The .env.example carries the chain switch: POLYMARKET_CHAIN_ID defaults to 137 for Polygon mainnet, with 80002 named for the Amoy testnet.

One detail in pyproject.toml deserves attention. The mcp dependency is pinned to mcp>=1.0.0,<2.0.0 with a comment explaining that MCP 2.0 removed the decorator API on Server that this codebase is built on. That pin is a deliberate freeze, not an oversight, and it means the project is not tracking the newest protocol surface.

Installing it and running a first read-only session

The README offers an automated installer and a manual path. The manual path is the one you can reason about. It clones the repository, creates a virtual environment, and installs the package in editable mode, which is what exposes the polymarket-mcp, polymarket-web and polymarket-setup console scripts declared in pyproject.toml.

git clone https://github.com/caiovicentino/polymarket-mcp-server.git
cd polymarket-mcp-server
python -m venv venv
source venv/bin/activate
pip install -e .

After that, configuration starts from the example environment file. The README's DEMO mode instruction is to copy .env.example to .env and edit it; the example file itself says DEMO_MODE=true means you do not need POLYGON_PRIVATE_KEY or POLYGON_ADDRESS, because the system falls back to safe demo values and trading functions are disabled.

cp .env.example .env
# then set DEMO_MODE=true in .env

With DEMO_MODE=true and no wallet fields filled in, the server should start in read-only mode. The README lists what stays available: market discovery and search, real-time market analysis, AI-powered insights, and price monitoring. Trading is off. That is the correct first session, because it exercises the API client and the tool surface without giving the process signing authority.

The README also documents a web dashboard as a separate entry point. Running polymarket-web, or the start_web_dashboard.sh script, serves a UI on http://localhost:8080 with live MCP status, configuration sliders for safety limits, market browsing and performance charts. If you would rather adjust limits through a form than edit environment variables, that is the path; the repository points to WEB_DASHBOARD.md for the full documentation.

The safety caps are the most interesting part of the design

Most MCP servers for financial APIs stop at authentication. This one ships a pre-trade validation layer, and the .env.example and docker-compose.yml show the actual keys: MAX_ORDER_SIZE_USD (default 1000), MAX_TOTAL_EXPOSURE_USD (default 10000), and REQUIRE_CONFIRMATION_ABOVE_USD (default 100). The README adds position limits per market, minimum liquidity requirements, spread tolerance checks, and pre-trade validation as a bundle, plus a confirmation flow for large orders.

Read those three numbers together and the intent is clear. A single order is capped at 1000 USD, total exposure at 10000 USD, and anything above 100 USD is supposed to stop and ask a human. The gap between 100 and 1000 is where the confirmation gate does its work. If you leave REQUIRE_CONFIRMATION_ABOVE_USD at its default, every order between 100 and 1000 USD should require an explicit approval before it reaches the exchange.

What the documentation does not spell out is the failure mode when confirmation is unavailable. If the MCP client disconnects mid-flow, or the model retries a call, the README does not describe what happens to a pending order. It also does not document a rollback path for a submitted order. Cancellation tools exist in the trading group, but cancellation is not the same as an atomic rollback, and the README does not claim otherwise. Treat the confirmation threshold as the primary control and set it deliberately rather than accepting the default.

Where it is the wrong tool

The private key requirement is the first disqualifier. .env.example instructs you to paste POLYGON_PRIVATE_KEY, exported from MetaMask, into a plaintext environment file, and docker-compose.yml passes it into the container as an environment variable. For a funded mainnet wallet, that is a custody decision, not a configuration detail. Anyone with read access to the file or the container's environment has the key. The repository's SECURITY.md exists, but nothing in the repository describes hardware-wallet signing, a separate signer process, or key isolation.

The second disqualifier is unattended operation. The README's own framing is autonomous trading, and the tools include natural-language trade execution and AI-suggested pricing. If you want a system that runs strategies on a schedule without a human in the loop, this server will do what the model asks within the caps, and the caps are the only thing standing between a bad model turn and an order. A dedicated execution bot with hard-coded strategy logic and no LLM in the signing path is the safer shape for that use case.

The third is protocol currency. Because of the mcp>=1.0.0,<2.0.0 pin, anyone building against MCP 2.0 features will find this server on the older decorator API. The pyproject comment says the pin holds until a migration lands, so the constraint is known, but it is a constraint.

Finally, the repository carries a large number of top-level markdown files (DOCKER.md, SETUP_GUIDE.md, INSTALLATION.md, QUICKSTART_GUIDE.md, FAQ.md, and more) alongside several analysis scripts. That volume of documentation is a maintenance signal in both directions: there is a lot to read, and a lot to keep in sync with the code.

How it compares with a direct py-clob-client integration

The obvious alternative is using py-clob-client directly, which is the same library this server depends on. Going direct means you write the market discovery, orderbook parsing, WebSocket reconnection and rate-limit logic yourself, and you decide exactly what the model is allowed to call. You get full control over signing, key handling and confirmation, and you can put the signer in a separate process. You also get all the work.

This server's difference is the tool layer. Forty-five pre-shaped tools with typed parameters are what let a model operate without prompt engineering per endpoint, and the safety caps are pre-wired rather than something you bolt on. The trade-off is the same as any wrapper: you inherit the author's choices about defaults, about which MCP protocol version you get, and about how credentials are stored. If your priority is auditability of every signing decision, direct integration wins. If your priority is having Claude query and trade markets this week, the tool layer is the reason to use this project.

A separate but related point: the README states there are no mocks and that integration is against real Polymarket APIs throughout. For anyone evaluating it, that means the test suite needs live credentials, which shapes how you would run it in CI.

Licence, releases and what upgrades cost

The licence is MIT, declared in the repository and shown in the README badge. MIT permits commercial use, modification and redistribution with the copyright notice retained; it also means the author offers no warranty, which matters more than usual for software that signs financial transactions. Nothing here constitutes legal advice, and if you redistribute a modified version you should read the LICENSE file rather than this paragraph.

The release history is short and uneven. v0.1.0 shipped on 2025-11-11 as the initial release, and v0.2.0 followed on 2026-07-30, roughly eight months later. The last push to the repository was on 2026-07-30, the same day as v0.2.0. Dependencies are declared with lower bounds rather than exact pins for most packages (py-clob-client>=0.28.0, websockets>=12.0, pydantic>=2.0.0), with the notable exception of the mcp pin. That means a fresh pip install -e . can resolve newer minor versions of trading-critical libraries than the author tested against, and the pyproject comment about ruff's default rule set silently turning CI red shows the author is aware of this class of drift.

Upgrade cost is therefore low in effort and non-trivial in risk. There is no documented migration guide between v0.1.0 and v0.2.0, so if you are already running the older release, the CHANGELOG.md in the repository is where you would look before pulling.

Editorial conclusion

Adopt it if you already hold a Polygon wallet and want Claude to query markets, orderbooks and positions without writing your own py-clob-client wrapper; run DEMO_MODE=true first and read the safety caps in .env.example before you put a key in the same file. Do not adopt it if you want a hosted service, a non-custodial signing flow, or an unattended strategy engine, because the private key sits in .env and the server executes what the model asks for. Verify two things before trading: that your installed mcp version still satisfies the mcp>=1.0.0,<2.0.0 pin, and that the confirmation threshold you set is low enough that no order above it can reach the exchange without a human reply.

Frequently asked questions

Official sources

1. caiovicentino/polymarket-mcp-server on GitHub
2. Issues
3. License: MIT
4. README
5. Releases