# Polymarket MCP Server 🔮⚡

[![npm version](https://img.shields.io/npm/v/polymarket-mcp-server?color=blue&logo=npm)](https://www.npmjs.com/package/polymarket-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MCP Protocol](https://img.shields.io/badge/MCP%20Protocol-2024--11--05-purple.svg)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/tests-34%20passed-brightgreen.svg)](https://github.com/nexosdata/polymarket-mcp-server)
[![Zero Runtime Dependencies](https://img.shields.io/badge/dependencies-0%20runtime-success.svg)](https://github.com/nexosdata/polymarket-mcp-server)

> **The premier Model Context Protocol (MCP) server for prediction markets.** Connect **Claude Desktop**, **Cursor IDE**, **Windsurf**, and autonomous quant agents directly to live Level 2 orderbook depth, cross-venue arbitrage detection, quadratic fee solvers, and whale block trade orderflow across **Polymarket**, **Kalshi**, **Limitless**, **PredictIt**, **ForecastEx**, **Smarkets**, and **Drift BET**.

---

## 📑 Table of Contents

- [Overview](#-overview)
- [Keywords & Target Capabilities](#-target-capabilities)
- [Architecture](#-architecture)
- [60-Second Setup](#-60-second-setup)
  - [Claude Desktop](#1-claude-desktop-setup)
  - [Cursor IDE](#2-cursor-ide-setup)
  - [Windsurf & Custom Agents](#3-windsurf--custom-agents)
- [MCP Tools Reference](#-mcp-tools-reference)
  - [`get_market_orderbook`](#1-get_market_orderbook)
  - [`scan_arbitrage_opportunities`](#2-scan_arbitrage_opportunities)
  - [`calculate_kalshi_fees`](#3-calculate_kalshi_fees)
  - [`get_whale_trades`](#4-get_whale_trades)
  - [`search_prediction_markets`](#5-search_prediction_markets)
- [Real-World LLM Prompts](#-real-world-llm-prompts)
- [NaxosData API Gateway Integration](#-naxosdata-api-gateway-integration)
- [CLI Utilities & Testing](#-cli-utilities--testing)
- [Development & Automated Tests](#-development--automated-tests)
- [License](#-license)

---

## 🚀 Overview

`polymarket-mcp-server` implements a lightweight, ultra-low latency JSON-RPC 2.0 stdio server compliant with the **Model Context Protocol (MCP) 2024-11-05 specification**.

Designed specifically for AI-driven quantitative analysis, market-making research, and prediction market trading, this server equips AI assistants with 5 institutional-grade financial tools:
1. **Level 2 Normalized Depth**: Real-time bid/ask ladders, mid-prices, basis point spreads, and Order Book Imbalance (OBI).
2. **Cross-Venue Matched Arbitrage**: Live scanner identifying pricing discrepancies between Polymarket and regulated exchanges like Kalshi or ForecastEx, complete with gross edge, net ROI, and annualized yields.
3. **Exact Quadratic Fee Solver**: Computes Kalshi CFTC Rule 40.2 quadratic taker fees (`ceil(0.07 * C * P * (1-P))`) and solves closed-form quadratic equations (`0.07*P^2 - 1.07*P + K >= 0`) for guaranteed positive-EV counterpart pricing.
4. **Institutional Whale Orderflow**: Live tape monitoring large block fills (> $5,000, > $50,000, > $100,000) with on-chain wallet addresses and Polygon transaction hashes.
5. **Multi-Venue Market Search**: Universal catalog query across 7 venues simultaneously.

---

## 🎯 Target Capabilities

- **Polymarket MCP Server**: Native integration for decentralized Polygon CLOB orderbooks.
- **Model Context Protocol**: Fully compliant MCP tool provider supporting `initialize`, `ping`, `tools/list`, and `tools/call`.
- **Claude Prediction Market**: Empowers Claude 3.5 Sonnet and Claude 3.7 with real-time financial mathematics.
- **Cursor Polymarket Tool**: Enables Cursor IDE developers to query live orderbooks and backtest strategies in chat.
- **Kalshi MCP**: CFTC-regulated binary contract fee modeling and cross-venue pairing.

---

## 📐 Architecture

```mermaid
flowchart TD
    subgraph Clients["AI Clients & IDEs"]
        CD["Claude Desktop"]
        CR["Cursor IDE"]
        WS["Windsurf / Agents"]
    end

    subgraph Server["polymarket-mcp-server"]
        STDIO["JSON-RPC 2.0 stdio Transport<br/>(Line-delimited & Content-Length)"]
        DISP["Tool Registry & Dispatcher"]
        MATH["Quadratic Fee & Breakeven Math Engine"]
        CLIENT["NaxosData API Client & Fallback Provider"]
    end

    subgraph Venues["Prediction Venues (7 Covered)"]
        POLY["Polymarket (Polygon L2 CLOB)"]
        KALSHI["Kalshi (CFTC Binary)"]
        FCX["ForecastEx (IBKR)"]
        LIMITLESS["Limitless Exchange"]
        PREDICTIT["PredictIt"]
        SMARKETS["Smarkets"]
        DRIFT["Drift BET (Solana)"]
    end

    CD <-->|stdio JSON-RPC| STDIO
    CR <-->|stdio JSON-RPC| STDIO
    WS <-->|stdio JSON-RPC| STDIO

    STDIO --> DISP
    DISP --> MATH
    DISP --> CLIENT

    CLIENT -->|NaxosData Gateway / Direct CLOB| Venues
```

---

## ⚡ 60-Second Setup

### 1. Claude Desktop Setup

Open your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Add the `polymarket` server to `mcpServers`:

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "polymarket-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here"
      }
    }
  }
}
```

> **Note**: `NAXOS_API_KEY` is optional for initial setup. When omitted, the server operates in public fallback mode. For live sub-second orderbooks and historical archives, provide a key from [naxosdata.com](https://naxosdata.com).

Restart Claude Desktop, and you will see the 🔨 tool icon active!

---

### 2. Cursor IDE Setup

In your project workspace, create or edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "polymarket-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here"
      }
    }
  }
}
```

Alternatively, open **Cursor Settings** → **Features** → **MCP** → **Add New MCP Server**:
- **Name**: `polymarket`
- **Type**: `command`
- **Command**: `npx -y polymarket-mcp-server`

---

### 3. Windsurf & Custom Agents

In `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "polymarket-mcp-server"]
    }
  }
}
```

---

## 🛠 MCP Tools Reference

### 1. `get_market_orderbook`

Retrieves normalized Level 2 orderbook depth for any contract across 7 venues. Returns bids, asks, best bid/ask, mid-price, spread in basis points, and top-5 Order Book Imbalance (OBI).

#### Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `market_id` | `string` | **Yes** | — | Market identifier, token condition ID, or venue slug |
| `venue` | `string` | No | `"POLYMARKET"` | `POLYMARKET`, `KALSHI`, `LIMITLESS`, `PREDICTIT`, `DRIFT_BET`, `SMARKETS`, `FORECASTEX` |
| `depth` | `number` | No | `5` | Number of bid/ask ladder rungs to fetch (1 - 50) |

#### Example Call:
```json
{
  "name": "get_market_orderbook",
  "arguments": {
    "market_id": "FED-DEC26-CUT",
    "venue": "KALSHI",
    "depth": 3
  }
}
```

#### Returns:
```json
{
  "venue": "KALSHI",
  "market_id": "FED-DEC26-CUT",
  "timestamp_ms": 1793558701534,
  "bids": [[0.52, 10107], [0.51, 15214], [0.50, 5321]],
  "asks": [[0.54, 6714], [0.55, 15821], [0.56, 8928]],
  "best_bid": 0.52,
  "best_ask": 0.54,
  "mid_price": 0.53,
  "spread_bps": 377.36,
  "obi_top5": -0.013,
  "top5_liquidity_usd": 32916,
  "microstructure": {
    "vwap_divergence_cents": 0.03,
    "wire_lag_ms": 18,
    "estimated_taker_fee_bps": 175
  }
}
```

---

### 2. `scan_arbitrage_opportunities`

Scans cross-venue matched prediction contract pairs (e.g., Polymarket YES vs Kalshi NO) where mutually exclusive outcomes are mispriced, guaranteeing a risk-free payout after fees.

#### Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `category` | `string` | No | `"ALL"` | Filter: `POLITICS`, `ECONOMICS`, `CRYPTO`, `SPORTS`, `ALL` |
| `min_net_roi_pct` | `number` | No | `0.5` | Minimum net ROI percentage after exchange taker fees and gas |
| `risk` | `string` | No | `"ALL"` | Oracle risk filter: `ALL`, `MINIMAL`, `LOW`, `MEDIUM` |
| `limit` | `number` | No | `10` | Max pairs to return (1 - 50) |

#### Example Call:
```json
{
  "name": "scan_arbitrage_opportunities",
  "arguments": {
    "category": "ECONOMICS",
    "min_net_roi_pct": 2.0
  }
}
```

---

### 3. `calculate_kalshi_fees`

Computes the CFTC-cleared Kalshi quadratic taker fee and solves the closed-form quadratic root solver to calculate the maximum price you can pay for a counterpart leg while achieving target net ROI.

$$\text{Kalshi Taker Fee} = \lceil 0.07 \cdot C \cdot P \cdot (1 - P) \rceil$$

$$0.07 \cdot P_{\text{no}}^2 - 1.07 \cdot P_{\text{no}} + K \ge 0 \quad \text{where } K = \frac{1}{1 + \frac{\text{ROI}}{100}} - P_{\text{poly}} - \text{Gas}$$

#### Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `contracts` | `number` | No | `100` | Number of contracts to trade |
| `price` | `number` | No | — | Kalshi contract price [0.01 - 0.99] for direct fee calculation |
| `primary_price` | `number` | No | — | Primary leg price (e.g. Polymarket YES at 0.46) to solve breakeven |
| `target_roi_pct` | `number` | No | `0.0` | Target net ROI percentage after all taker fees & gas |

#### Example Call:
```json
{
  "name": "calculate_kalshi_fees",
  "arguments": {
    "contracts": 100,
    "price": 0.52,
    "primary_price": 0.46,
    "target_roi_pct": 2.5
  }
}
```

#### Returns:
```json
{
  "contracts": 100,
  "price": 0.52,
  "calculated_fee_usd": 1.75,
  "fee_per_contract_cents": 1.75,
  "quadratic_solution": {
    "primaryPrice": 0.46,
    "targetRoiPct": 2.5,
    "contracts": 100,
    "primaryFeeCents": 0.008,
    "maxCounterpartPrice": 0.498,
    "maxCounterpartCents": 49.8,
    "counterpartFeeCents": 1.75,
    "totalCostCents": 97.56,
    "netMarginCents": 2.44,
    "isProfitable": true
  }
}
```

---

### 4. `get_whale_trades`

Monitors institutional orderflow and block trades with verified on-chain Polygon wallet addresses, transaction hashes, and trade sizes.

#### Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `venue` | `string` | No | `"POLYMARKET"` | `POLYMARKET`, `KALSHI`, `LIMITLESS`, `ALL` |
| `market_id` | `string` | No | — | Filter by specific market identifier or slug |
| `min_size_usd` | `number` | No | `5000` | Minimum trade notional size in USD |
| `limit` | `number` | No | `10` | Max trades to return |

---

### 5. `search_prediction_markets`

Universal search engine indexing active contracts across all 7 prediction venues with 24-hour volume, liquidity, and oracle specifications.

#### Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | `string` | **Yes** | — | Search term (e.g., `"Trump"`, `"Fed"`, `"Bitcoin"`, `"CPI"`) |
| `venue` | `string` | No | `"ALL"` | Venue filter or `"ALL"` |
| `category` | `string` | No | — | Filter by category (`POLITICS`, `ECONOMICS`, `CRYPTO`, etc.) |
| `status` | `string` | No | `"ACTIVE"` | `"ACTIVE"`, `"RESOLVED"`, `"ALL"` |
| `limit` | `number` | No | `10` | Max markets to return |

---

## 💬 Real-World LLM Prompts

Once configured in Claude Desktop or Cursor, try asking:

```text
"Search for active prediction markets related to the Federal Reserve December 2026 interest rate decision across all venues."
```

```text
"Scan cross-venue arbitrage pairs in the ECONOMICS category with a minimum net ROI of 2%. Show me the exact execution breakdown."
```

```text
"If Polymarket YES for the Fed rate cut is trading at $0.46, what is the maximum price I can pay on Kalshi NO for 100 contracts to lock in at least 2.5% net ROI after Kalshi's quadratic taker fee?"
```

```text
"Show me recent whale block trades over $25,000 on Polymarket and give me the wallet addresses and transaction hashes."
```

```text
"Fetch the Level 2 orderbook for FED-DEC26-CUT on Kalshi and calculate the Order Book Imbalance (OBI)."
```

---

## 🌐 NaxosData API Gateway Integration

`polymarket-mcp-server` integrates seamlessly with **NaxosData**, the leading L2 historical archive and real-time streaming feed provider for prediction markets.

To connect your server to institutional endpoints:

1. Obtain an API key from [naxosdata.com](https://naxosdata.com).
2. Set the environment variable:
   ```bash
   export NAXOS_API_KEY="nx_live_your_api_key_here"
   ```
3. Or configure it in your `claude_desktop_config.json` / `.cursor/mcp.json`.

Supported key prefixes: `nx_live_...`, `nx_pro_...`, `nx_inst_...`, `nx_free_...`.

---

## 💻 CLI Utilities & Testing

You can inspect and execute MCP tools directly from the terminal without launching an MCP client:

```bash
# Print help and usage
npx polymarket-mcp-server --help

# List all available tool schemas
npx polymarket-mcp-server --tools

# Test direct execution of a tool
npx polymarket-mcp-server --test-call calculate_kalshi_fees '{"contracts":100,"price":0.52,"primary_price":0.46,"target_roi_pct":2.5}'

# Test market search
npx polymarket-mcp-server --test-call search_prediction_markets '{"query":"Trump","limit":3}'

# Test orderbook snapshot
npx polymarket-mcp-server --test-call get_market_orderbook '{"market_id":"FED-DEC26-CUT","venue":"KALSHI","depth":3}'
```

---

## 🧪 Development & Automated Tests

This repository is built with **100% strict TypeScript** and features an automated test suite executed via the native Node.js test runner (`node:test`).

```bash
# Clone the repository
git clone https://github.com/nexosdata/polymarket-mcp-server.git
cd polymarket-mcp-server

# Install dev dependencies
npm install

# Compile TypeScript
npm run build

# Run full test suite (34 test cases across all JSON-RPC methods and math solvers)
npm test
```

### Test Coverage Highlights:
- **Protocol Compliance**: JSON-RPC 2.0 handshakes, protocol version `2024-11-05`, ping, notifications, error codes (-32700, -32600, -32601, -32602).
- **Transport Framing**: Line-delimited JSON and Content-Length framed byte streams.
- **Quantitative Solvers**: Exact boundary tests for Kalshi quadratic fee formulas, `ceilCents()` rounding invariants, and closed-form quadratic root solver limits.
- **Tool Validation**: Strict schema validation for all 5 MCP endpoints.

---

## 📜 License

MIT License. Copyright (c) 2026 **NaxosData Contributors & William Gonda**.  
See the [LICENSE](LICENSE) file for complete details.