The Polymarket MCP Server gives AI assistants read access to Polymarket prediction markets via 23 tools, 5 resources, and 4 prompts — no API keys or configuration required.
Market Discovery & Filtering
List, filter, and paginate events and markets by volume, liquidity, tags, status, and date ranges
Full-text search across events, markets, and profiles
Browse category tags, event series, sports, and sports teams
Real-Time Price & Order Book Data
Get current buy/sell prices, midpoint prices, and last trade prices
Access full order book depth (single or batch up to 20 tokens)
View order book summaries (best bid, ask, spread) and minimum tick sizes
Retrieve CLOB market details (tokens, rewards, trading parameters)
Trades & Holders
View recent trade history (trader, side, size, price, timestamp)
Identify top position holders and their position sizes for any market
Guided Analysis Workflows
Deep-dive market analysis (probability, liquidity, order book depth, top holders)
Side-by-side market comparison
Trending markets discovery by volume
Sports prediction markets overview
Production-Grade Features
Rate limiting per API endpoint (Gamma: 4k/10s, CLOB: 9k/10s, Data: 1k/10s)
Smart in-memory caching (order books: 5s, markets: 30s, tags: 5min)
Exponential backoff retries and request timeouts
URI-based resource access for markets, events, order books, and tags
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Polymarket MCP Server What are the trending prediction markets by volume right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Prediction markets are the best real-time signal for what the world thinks will happen next. This server puts that signal directly into your AI assistant's toolkit — no API keys, no auth tokens, no setup hassle.
23 tools • 5 resources • 4 prompts • Zero config • Zero dependencies beyond the MCP SDK
Related MCP server: Polymarket MCP Server
Add to your claude_desktop_config.json (Settings > Developer > Edit Config):
{
"mcpServers": {
"polymarket": {
"command": "npx",
"args": ["-y", "@yigit/polymarket-mcp"]
}
}
}Restart Claude Desktop. Done.
claude mcp add polymarket -- npx -y @yigit/polymarket-mcpgit clone https://github.com/yigitabi5444/yigit_polymarket_mcp.git
cd yigit_polymarket_mcp
npm install && npm run build
node dist/index.js # runs over stdioThen point your MCP client at the built binary:
{
"mcpServers": {
"polymarket": {
"command": "node",
"args": ["/absolute/path/to/yigit_polymarket_mcp/dist/index.js"]
}
}
}Tool | What it does |
| List/filter events — paginate, sort by volume/liquidity, filter by tag/status |
| Single event by ID or slug |
| List/filter markets with rich filtering (volume, liquidity, dates, tags) |
| Single market by ID or slug |
| Full-text search across events, markets, and profiles |
| List all category tags |
| List event series (grouped collections) |
| Get a specific series by ID |
| List available sports |
| List teams for a sport |
Tool | What it does |
| Current price for a token (buy/sell side) |
| Midpoint price (best bid + best ask / 2) |
| Last executed trade price |
| Historical price time series (configurable interval + fidelity) |
| Full bid/ask depth for a token |
| Batch order books for multiple tokens |
| Best bid, best ask, and spread at a glance |
| CLOB market details by condition ID |
| Markets eligible for liquidity rewards |
| Simplified sampled markets |
| Minimum price increment for a token |
Tool | What it does |
| Recent trades for a market |
| Top holders / position breakdown for a market |
URI Pattern | Description |
| Market JSON by slug |
| Event JSON by slug |
| CLOB market by condition ID |
| Live order book for a token |
| All category tags (cached) |
Prompt | Description |
| Deep-dive: probability, liquidity, order book depth, top holders |
| Side-by-side comparison of multiple markets |
| Find the hottest markets by volume right now |
| Overview of sports prediction markets |
┌─────────────────────────────┐
│ MCP Client │
│ (Claude Desktop / Code) │
└─────────┬───────────────────┘
│ stdio (JSON-RPC)
┌─────────▼───────────────────┐
│ polymarket-mcp │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Tools │ │Resources │ │
│ │ (22) │ │ (5) │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ ┌────▼─────────────▼─────┐ │
│ │ API Client │ │
│ │ ┌───────┐ ┌────────┐ │ │
│ │ │ Rate │ │ Cache │ │ │
│ │ │Limiter│ │ (TTL) │ │ │
│ │ └───┬───┘ └───┬────┘ │ │
│ │ │ │ │ │
│ │ ┌───▼─────────▼────┐ │ │
│ │ │ Retry + Backoff │ │ │
│ │ └──────────────────┘ │ │
│ └────────────────────────┘ │
└──────────┬───────────────────┘
│ HTTPS
┌──────────▼───────────────────┐
│ Polymarket APIs │
│ gamma-api · clob · data-api │
└──────────────────────────────┘List endpoints (get_markets, get_events) default to active=true, closed=false, order=volume descending — you get the hottest live markets out of the box, not ancient resolved ones from 2020. Override any default explicitly when you need historical data.
Raw Polymarket API responses contain 50+ fields per market (including gems like pagerDutyNotificationEnabled and mailchimpTag). This server strips the noise and returns a curated subset. JSON-encoded strings like outcomes and outcomePrices are parsed into real arrays — ["Yes", "No"] not "[\"Yes\", \"No\"]".
Feature | Implementation |
Rate limiting | Token-bucket per API endpoint (Gamma: 4k/10s, CLOB: 9k/10s, Data: 1k/10s) |
Caching | In-memory TTL cache (order books: 5s, markets: 30s, tags: 5min) |
Retries | Exponential backoff with jitter on 429s and 5xx errors (3 retries max) |
Timeouts | 15s request timeout on all API calls |
No auth | Only hits public endpoints — zero secrets to manage |
No deps | Uses native |
Type safety | Full TypeScript with strict mode, Zod validation on all inputs |
Environment Variable | Default | Description |
|
| Set to |
That's it. No API keys, no tokens, no config files. It just works.
npm install # install dependencies
npm run build # compile TypeScript
npm run dev # run with tsx (auto-reload)
npm test # run test suite
npm run test:watch # tests in watch modesrc/
├── index.ts # stdio entrypoint
├── server.ts # MCP server factory
├── config.ts # rate limits, cache TTLs, timeouts
├── api/
│ ├── client.ts # HTTP client with retry + rate limiting
│ ├── cache.ts # TTL cache implementation
│ ├── rate-limiter.ts # token-bucket rate limiter
│ ├── gamma.ts # Gamma API wrapper
│ ├── clob.ts # CLOB API wrapper
│ └── data.ts # Data API wrapper
├── tools/
│ ├── gamma/ # 6 Gamma tools
│ ├── clob/ # 4 CLOB tools
│ └── data/ # 2 Data tools
├── resources/ # 5 URI-based resources
├── prompts/ # 4 guided analysis prompts
└── types/ # TypeScript type definitionsYou: What are the hottest prediction markets right now?
Claude: uses
get_marketssorted by volume, thenget_order_bookfor depth analysis
You: What's the current probability that Bitcoin hits $200k this year?
Claude: uses
search("bitcoin 200k"), thenget_pricefor live odds
You: Compare the presidential election markets
Claude: uses the
compare_marketsprompt with relevant slugs
You: Show me the order book for the top sports market
Claude: uses
get_sports→get_markets→get_order_book
PRs welcome! Please:
Fork the repo
Create a feature branch (git checkout -b feature/awesome)
Add tests for new functionality
Make sure npm test passes
Submit a PR
MIT — do whatever you want with it.
Get CLOB-specific market details by condition ID. Returns tokens, rewards, tick sizes, and trading parameters.
Inputs: condition_id (required).
Get a single Polymarket event by ID or slug. Returns full event details including nested markets.
Inputs: id, slug.
List and filter Polymarket prediction events. Supports pagination, sorting, and filtering by status/tag.
Inputs: limit, offset, order, ascending, +4 more.
Get the last executed trade price for a Polymarket token.
Inputs: token_id (required).
Get a single Polymarket market by ID or slug. Returns full market details including outcomes, prices, volume, and liquidity.
Inputs: id, slug.
Get top holders/positions for a Polymarket market. Shows the largest positions and who holds them.
Inputs: condition_id (required), limit, offset.
List and filter Polymarket prediction markets. Supports rich filtering by volume, liquidity, dates, tags, and status. Sort by volume descending to find the most active markets.
Inputs: limit, offset, order, ascending, +12 more.
Get recent trades for a Polymarket market. Shows who traded, which side, size, price, and timestamp.
Inputs: condition_id (required), limit, offset.
Get the midpoint price for a Polymarket token (average of best bid and ask).
Inputs: token_id (required).
Get the full order book (bids and asks) for a Polymarket token. Shows market depth and liquidity at each price level.
Inputs: token_id (required).
Get order books for multiple Polymarket tokens in a single batch request.
Inputs: token_ids (required).
Get a summarized order book for a Polymarket token: best bid, best ask, and spread.
Inputs: token_id (required).
Get the current price for a Polymarket token on the given side (buy or sell). Returns the best available price.
Inputs: token_id (required), side (required).
Get currently sampled Polymarket markets that are eligible for liquidity rewards.
Inputs: no named parameters.
Get simplified view of currently sampled Polymarket markets.
Inputs: no named parameters.
List Polymarket event series (grouped collections of related events).
Inputs: limit, offset.
Get a specific Polymarket event series by ID, including all events in the series.
Inputs: id (required).
List available sports on Polymarket (e.g. NBA, NFL, EPL, MLB).
Inputs: no named parameters.
List teams for a given sport on Polymarket.
Inputs: sport.
List all available Polymarket category tags. Use these tags to filter markets and events.
Inputs: no named parameters.
Get the minimum tick size (price increment) for a Polymarket token.
Inputs: token_id (required).
Full-text search across Polymarket events, markets, and profiles. Use this to find markets on any topic.
Inputs: query (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 22 tools
Most tools have distinct purposes, but there is notable overlap between get_event/get_market and get_events/get_markets, which could cause confusion about when to use each. Additionally, get_order_book, get_order_book_summary, and get_midpoint all relate to order book data, creating some redundancy in the set.
All tool names follow a consistent snake_case pattern with a clear 'get_' prefix, making them predictable and easy to parse. The naming scheme is uniform across all 22 tools, with no deviations in style or structure.
With 22 tools, the count is borderline high for a prediction market server, leaning toward heavy. While Polymarket has a complex domain, the tool set includes multiple similar tools (e.g., order book variants) that could have been consolidated, making it feel slightly over-scoped.
The tool set provides comprehensive read-only coverage for exploring Polymarket data, including events, markets, trades, order books, and metadata. However, it lacks write operations (e.g., placing trades or managing positions), which are core to a trading platform, leaving a minor but notable gap for full agent interaction.
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Read-only Polymarket search, market details, order books, price history, and market cards.
Fetches live Polymarket prediction market orderbooks, implied Yes/No probabilities, volume, and wh
Live Polymarket odds, order books, fee-inclusive quotes and non-custodial prediction trading.