MCP 服务器

Polymarket MCP Server

Enables comprehensive read access to Polymarket prediction market data, including live prices, order books, and market statistics. It allows AI assistants to analyze events, search markets, and monitor real-time signals without requiring API keys or authentication.

README

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

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

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:

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

License

MIT — do whatever you want with it.

Built with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>