polymarket-mcp

polymarket-mcp

A production-grade MCP server for Polymarket 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

CLOB API — Prices & Order Books

Data API — Trades & Holders

Resources (URI-based access)

Prompts (guided workflows)

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

Configuration

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.

_{Built with the Model Context Protocol}