Polymarket MCP Server

<p align="center"> <img src="https://polymarket.com/icons/favicon-196x196.png" width="80" height="80" alt="Polymarket logo" /> </p>

<h1 align="center">polymarket-mcp</h1>

<p align="center"> <strong>A production-grade MCP server for <a href="https://polymarket.com">Polymarket</a> prediction markets.</strong><br/> Give Claude (or any MCP client) full read access to every public Polymarket API. </p>

<p align="center"> <a href="#quick-start"><img src="https://img.shields.io/badge/Get_Started-blue?style=for-the-badge" alt="Get Started" /></a>  <a href="https://www.npmjs.com/package/@yigit/polymarket-mcp"><img src="https://img.shields.io/npm/v/@yigit/polymarket-mcp?style=for-the-badge&logo=npm&color=cb3837" alt="npm" /></a>  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License" /></a>  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=for-the-badge" alt="MCP Compatible" /></a> </p>

---

Why?

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

---

Quick Start

Option 1: Claude Desktop

Add to your claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "@yigit/polymarket-mcp"]
    }
  }
}

Restart Claude Desktop. Done.

Option 2: Claude Code

claude mcp add polymarket -- npx -y @yigit/polymarket-mcp

Option 3: Build from source

git clone https://github.com/yigitabi5444/yigit_polymarket_mcp.git
cd yigit_polymarket_mcp
npm install && npm run build
node dist/index.js  # runs over stdio

Then point your MCP client at the built binary:

{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/absolute/path/to/yigit_polymarket_mcp/dist/index.js"]
    }
  }
}

---

What Can It Do?

Gamma API — Events & Markets

Tool	What it does
get_events	List/filter events — paginate, sort by volume/liquidity, filter by tag/status
get_event	Single event by ID or slug
get_markets	List/filter markets with rich filtering (volume, liquidity, dates, tags)
get_market	Single market by ID or slug
search	Full-text search across events, markets, and profiles
get_tags	List all category tags
get_series	List event series (grouped collections)
get_series_by_id	Get a specific series by ID
get_sports	List available sports
get_sports_teams	List teams for a sport

CLOB API — Prices & Order Books

Tool	What it does
get_price	Current price for a token (buy/sell side)
get_midpoint	Midpoint price (best bid + best ask / 2)
get_last_trade_price	Last executed trade price
get_price_history	Historical price time series (configurable interval + fidelity)
get_order_book	Full bid/ask depth for a token
get_order_books	Batch order books for multiple tokens
get_order_book_summary	Best bid, best ask, and spread at a glance
get_clob_market	CLOB market details by condition ID
get_sampling_markets	Markets eligible for liquidity rewards
get_sampling_simplified_markets	Simplified sampled markets
get_tick_size	Minimum price increment for a token

Data API — Trades & Holders

Tool	What it does
get_market_trades	Recent trades for a market
get_market_holders	Top holders / position breakdown for a market

Resources (URI-based access)

URI Pattern	Description
market://slug/{slug}	Market JSON by slug
event://slug/{slug}	Event JSON by slug
market://condition/{id}	CLOB market by condition ID
orderbook://token/{id}	Live order book for a token
tags://all	All category tags (cached)

Prompts (guided workflows)

Prompt	Description
analyze_market	Deep-dive: probability, liquidity, order book depth, top holders
compare_markets	Side-by-side comparison of multiple markets
trending_markets	Find the hottest markets by volume right now
sports_overview	Overview of sports prediction markets

---

Architecture

┌─────────────────────────────┐
│        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 │
└──────────────────────────────┘

Smart Defaults

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.

Clean Responses

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\"]".

Production Hardening

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 fetch — no axios, no node-fetch, just the MCP SDK + Zod
Type safety	Full TypeScript with strict mode, Zod validation on all inputs

---

Configuration

Environment Variable	Default	Description
POLYMARKET_CACHE_DISABLED	false	Set to true to disable all caching

That's it. No API keys, no tokens, no config files. It just works.

---

Development

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 mode

Project Structure

src/
├── 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 definitions

---

Example Conversations

You: What are the hottest prediction markets right now?

Claude: uses get_markets sorted by volume, then get_order_book for depth analysis

You: What's the current probability that Bitcoin hits $200k this year?

Claude: uses search("bitcoin 200k"), then get_price for live odds

You: Compare the presidential election markets

Claude: uses the compare_markets prompt with relevant slugs

You: Show me the order book for the top sports market

Claude: uses get_sports → get_markets → get_order_book

---

Contributing

PRs welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/awesome)
3. Add tests for new functionality
4. Make sure npm test passes
5. Submit a PR

---

License

MIT — do whatever you want with it.

---

<p align="center"> _{Built with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>} </p>