How do I use Polymarket MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

Polymarket MCP Server by yigitabi5444

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.

22 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_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 │
└──────────────────────────────┘

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.

Polymarket MCP Server