Prediction Markets MCP Server

CI codecov License: MIT

An MCP server providing unified access to prediction market data from Kalshi and Polymarket.

[!WARNING] This project is in early development. APIs may change without notice.

Why Use This?

Prediction markets aggregate crowd wisdom into real-time probabilities. This MCP server lets you:

• Unify platforms — Query Kalshi and Polymarket through one interface
• Use natural language — Ask "What are the odds?" instead of parsing JSON APIs
• Get real-time data — Access prices, orderbooks, and trade history instantly
• Search efficiently — Full-text search across thousands of markets in <1ms

Instead of manually browsing market websites or writing API integration code, ask your AI assistant directly.

What Can You Ask?

Once connected, try these natural language queries:

• "What are the current odds on Polymarket for the next Fed rate decision?"
• "Show me all open Kalshi markets about the 2024 election"
• "Search Kalshi for markets about climate change"
• "Show me the orderbook for the next Fed rate decision on Kalshi"

Quick Start

Add to your MCP client configuration (e.g., ~/.claude.json for Claude Code):

{
  "mcpServers": {
    "prediction-markets": {
      "command": "npx",
      "args": ["-y", "prediction-mcp"],
      "env": {
        "KALSHI_API_KEY": "your-api-key",
        "KALSHI_PRIVATE_KEY_PATH": "/path/to/key.pem"
      }
    }
  }
}

Note: Polymarket works without credentials. Kalshi credentials are optional but required for authenticated operations.

Restart your MCP client to load the server.

📖 Full documentation — Setup guides for 7 MCP clients, troubleshooting, and more.

Installation

This server is published on npm and runs via npx. No cloning or building required.

Configuration Format

Most MCP clients use the same JSON structure:

{
  "mcpServers": {
    "prediction-markets": {
      "command": "npx",
      "args": ["-y", "prediction-mcp"],
      "env": {
        "KALSHI_API_KEY": "your-api-key",
        "KALSHI_PRIVATE_KEY_PATH": "/path/to/key.pem"
      }
    }
  }
}

Alternative runtimes: If you prefer Bun, use "command": "bunx" and "args": ["prediction-mcp"].

Client-Specific Locations

Client	Configuration File
Claude Code	.mcp.json (project root) or ~/.claude.json (global)
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
VS Code (Copilot)	.vscode/mcp.json (uses "servers" key instead of "mcpServers")
Cursor	.cursor/mcp.json or Cursor settings

See the Getting Started guide for detailed setup instructions for all supported clients.

Credentials

Kalshi

Kalshi requires API credentials for authenticated requests:

KALSHI_API_KEY=your-api-key-id
KALSHI_PRIVATE_KEY_PATH=/path/to/private-key.pem

Get credentials at kalshi.com/account/profile.

Demo Environment

Kalshi provides a demo environment for testing with mock funds:

KALSHI_USE_DEMO=true

Demo credentials are separate from production—create a demo account at demo.kalshi.co.

Polymarket

Polymarket tools work without authentication—all read operations are public.

Available Tools

Platform	Tools
Kalshi	kalshi_list_markets, kalshi_get_market, kalshi_get_orderbook, kalshi_get_trades, kalshi_search, etc.
Polymarket	polymarket_list_markets, polymarket_get_market, polymarket_get_orderbook, polymarket_get_price, etc.

See Tools Reference for the full tool reference with parameters.

Run bun run docs:generate after modifying tools to keep documentation in sync.

Development

For contributors working on this project:

git clone https://github.com/shaanmajid/prediction-mcp.git
cd prediction-mcp
bun install

bun test              # Run tests
bun run typecheck     # Type check
bun run lint          # Lint
bun run format        # Format

Pre-commit hooks run these checks automatically via Husky.

Documentation

bun run docs:generate  # Regenerate docs from source
bun run docs:check     # Verify docs match source (CI uses this)
bun run docs:serve     # Preview at localhost:8000

Project Structure

index.ts              # Server entry point
src/
  clients/
    kalshi.ts         # Kalshi API client
    polymarket.ts     # Polymarket Gamma + CLOB client
  search/
    cache.ts          # Search index
    service.ts        # Search lifecycle
  tools.ts            # MCP tool handlers
  validation.ts       # Zod schemas
scripts/
  bootstrap.ts        # MCP registration helper
  docs.ts             # Doc generator CLI

Links

• Documentation (hosted) · docs/ (source)
• Tools Reference
• Configuration
• Kalshi API
• Polymarket API
• MCP Protocol