polymarket-mcp

Clean, NegRisk-resolved Polymarket market & order-book data as an MCP server. No API key, no database — stateless wrappers over the public Gamma and CLOB APIs, with the messy parts (keyset pagination, NegRisk flags, token→outcome resolution, book parsing) already handled for you.

Point any MCP client (Claude Desktop, Cowork, Cursor, …) at it and your agent can query prediction-market data directly.

Tools

Tool	What it does
`polymarket_get_markets`	Top active markets by liquidity or 24h volume. Returns question, conditionId, outcome→tokenId mapping, negRisk flag, event, liquidity, volume, best bid/ask, spread. Filters: `limit`, `order_by`, `min_liquidity`, `contains`, `neg_risk_only`.
`polymarket_get_orderbook`	Live CLOB order book(s) for one or more outcome token ids. Sorted bids/asks + best bid/ask, spread, midpoint.
`polymarket_resolve_token`	Resolve a `token_id`, `condition_id`, or `slug` to its market and outcome mapping (which outcome the token is, its siblings).
`polymarket_resolve_token_onchain`	On-chain-verified resolution: derives `conditionId` + `outcomeIndex` from Polygon ground truth (CTF Exchange registry → ConditionalTokens position ids) instead of trusting the API. Returns block provenance + verification level (`fully_verified`, or `pair_only` for NegRisk). Requires `POLYGON_RPC_URL`.

Install & run

Requires Node 18+ (uses the built-in fetch).

npm install
npm run build

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "polymarket": { "command": "node", "args": ["/absolute/path/to/polymarket-mcp/dist/server.js"] }
  }
}

Then ask your agent things like "what are the most active Polymarket markets right now?" or "get the order book for this token id".

Try it without a client

npm run build && npm run smoke   # drives the server over stdio against live APIs

Tests

npm test   # unit tests for the ABI encoders — pure, no network

The encoder tests are deliberately network-free so they run anywhere. The API and on-chain paths are verified against live endpoints by hand (see npm run smoke), since CI has no route to Polymarket or a Polygon RPC.

Config (all optional)

Env	Default
`GAMMA_BASE_URL`	`https://gamma-api.polymarket.com`
`CLOB_BASE_URL`	`https://clob.polymarket.com`
`FETCH_TIMEOUT_MS`	`15000`
`POLYGON_RPC_URL`	(unset) — required only for `polymarket_resolve_token_onchain`. Any Polygon RPC that serves `eth_call` works; see below

Picking a Polygon RPC

The tool only needs eth_blockNumber and eth_call, so a free keyless endpoint is enough. Verified working without an API key:

export POLYGON_RPC_URL="https://polygon-bor-rpc.publicnode.com"

https://polygon.drpc.org and https://1rpc.io/matic also answer keyless. Note that https://polygon-rpc.com and https://rpc.ankr.com/polygon now return 401 / Unauthorized and require an account.

Passing the optional block argument reads historical state, which needs an archive node — most free endpoints reject it (publicnode returns "Archive requests require a personal token"). The tool surfaces that as an error rather than pretending the token is unregistered. Omit block to read latest.

Notes

Read-only. No trading, no orders, no keys. It reads public data.
Every fetch has a hard timeout + backstop so a stalled upstream can't hang the server.
This is a data-access tool, not trading advice. Prices and books are live public data; verify before acting on them.

License

MIT