Polymarket US Read-only
PASS WITH FIXES Tested on Composer 2.5, , result: PASS WITH FIXES. We built the server from the prompt with the Python MCP SDK (1 test passing) and confirmed it starts over stdio. Tool calls from a live MCP client were not exercised. It is read-only by design: no keys, orders or money. The prompt below includes the fixes from that run.
Short answer: A read-only Polymarket MCP server is a small local process that gives Claude Code, Cursor or any MCP client four tools (search markets, get market, best bid/offer, order book) backed by Polymarket US public endpoints. It needs no API key and has no trading tools, so your AI tool can research markets without being able to place orders.
GET /v1/search, GET /v1/market/slug/{slug}, GET /v1/markets/{slug}/bbo, GET /v1/markets/{slug}/book on https://gateway.polymarket.us.claude mcp add --transport stdio <name> -- <command>. Everything after -- is the command that runs your server.A local MCP server exposing four read-only tools (search markets, get market, get best bid/offer, get order book) backed by Polymarket US public endpoints, registered in your AI tool.
Builders who want their AI assistant to answer "what's the current price on X?" from live data while they code or research.
Not for: Giving an AI agent the ability to trade. Order tools are deliberately left out.
Works in Claude Code, Cursor, Codex/ChatGPT, Grok or any agent that can write files. Paste it into an empty folder. Read what it builds before you run anything.
Build a READ-ONLY MCP server for Polymarket US market data.
Use the official MCP SDK (TypeScript @modelcontextprotocol/sdk, or the
official Python SDK: pip install "mcp[cli]", Python 3.11+,
`from mcp.server import MCPServer` with @mcp.tool(); read
https://modelcontextprotocol.io and the SDK docs before coding) and the stdio
transport.
Tools (all read-only, no auth, base https://gateway.polymarket.us):
- search_markets(query: string, limit?: number<=20) -> GET /v1/search?query=
(returns {"events": [...]}, each event holding its markets; flatten to
one row per market with the event title)
- get_market(slug: string) -> GET /v1/market/slug/{slug}
- get_bbo(slug: string) -> GET /v1/markets/{slug}/bbo
- get_order_book(slug: string, depth?: number<=10) -> GET /v1/markets/{slug}/book
Rules:
- NO trading, preview, cancel, account or portfolio tools. Do not read any
POLYMARKET_* key env vars. Add a startup check that exits with an error if
POLYMARKET_SECRET_KEY is set, so this server can never be pointed at a key.
- Return compact JSON: question, slug, YES best bid/ask/last as decimals,
implied %, minimumTradeQty, orderPriceMinTickSize, and a note that prices
are the YES/long side.
- Validate inputs (slug format, limits). Time out HTTP calls at 10s.
- Cache responses 15s; stay far below the 25 req/s limit; back off on 429.
- Every tool response ends with: "Market data only. Not advice."
- README: how to build and how to register it with
`claude mcp add --transport stdio polymarket-readonly -- <command>`
and with Cursor's MCP settings.
- Tests for input validation and response shaping (mock HTTP).
Show the plan, build, then give me the exact register command..gitignore from the Safety Pack.claude mcp add --transport stdio polymarket-readonly -- node /full/path/to/dist/index.js or for Python claude mcp add --transport stdio polymarket-readonly -- python3 /full/path/to/server.py. In Cursor, add it in the MCP settings.search_markets, then get_bbo.This server can't trade, so there's nothing to paper-trade. The habit to build: when your assistant uses these tools to reason about a market, have it write its reasoning and the data snapshot to a file. If you later build a bot on that reasoning, you'll have a paper record to judge it against.
Tick every box before the bot touches real money. The full rules file, .gitignore and pre-commit hook are in the Safety Pack.
.env and *.pem are in .gitignore, and your AI tool is blocked from reading them (see the Safety Pack).touch KILL) stops new orders immediately, and a second command cancels every resting order through the venue's cancel-all endpoint.--live flag and a typed confirmation, and you only flip it after days of clean paper logs.Endpoints and rules were checked against these pages on Oct 19, 2026. APIs change, so if something here disagrees with the official docs, trust the docs and tell us.
We didn't find one in Polymarket US's official docs as of October 19, 2026. Community servers exist. Building your own read-only server takes about an hour and means you know exactly what it can do.
An MCP tool can be called by the AI on its own initiative, and AI agents make mistakes or can be steered by text they read. Keeping order tools out of the agent's reach removes the worst failure mode entirely.
For a local server, use claude mcp add --transport stdio <name> -- <command and args>. For a remote one, use claude mcp add --transport http <name> <url>.
No. All four tools use Polymarket US public endpoints, which don't need authentication.
One new build recipe, one safety tip, and API changes worth knowing about. Free. No picks, ever.
A copy-paste AI prompt and step-by-step guide to the Polymarket US API: public market data with no key, then authenticated reads. Includes the international Gamma API, read-only, with a geoblock check.
Step-by-step: use Claude Code to build a Polymarket US trading bot that runs in paper mode by default, with a local paper ledger, order preview, hard position limits and a kill switch.
An honest guide to building a trading bot with Claude, Claude Code or Claude AI: where it helps, where it fails, and a safe Kalshi-demo starter prompt with a rules file, deny settings, limits and a kill switch.