Skip to main content
Glama
polymarket-mcp-server
by nexosdata

Polymarket MCP Server ๐Ÿ”ฎโšก

npm version License: MIT MCP Protocol TypeScript Tests Zero Runtime Dependencies

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


Related MCP server: orcalayer-mcp

๐Ÿš€ 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

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:

{
  "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.

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:

{
  "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:

{
  "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:

{
  "name": "get_market_orderbook",
  "arguments": {
    "market_id": "FED-DEC26-CUT",
    "venue": "KALSHI",
    "depth": 3
  }
}

Returns:

{
  "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:

{
  "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:

{
  "name": "calculate_kalshi_fees",
  "arguments": {
    "contracts": 100,
    "price": 0.52,
    "primary_price": 0.46,
    "target_roi_pct": 2.5
  }
}

Returns:

{
  "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:

"Search for active prediction markets related to the Federal Reserve December 2026 interest rate decision across all venues."
"Scan cross-venue arbitrage pairs in the ECONOMICS category with a minimum net ROI of 2%. Show me the exact execution breakdown."
"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?"
"Show me recent whale block trades over $25,000 on Polymarket and give me the wallet addresses and transaction hashes."
"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.

  2. Set the environment variable:

    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:

# 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).

# 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 file for complete details.

Available Tools

5 tools
calculate_kalshi_feesB

Solve exact quadratic taker fees and maximum counterpart contract prices for Kalshi. Implements CFTC Rule 40.2 quadratic fee formula: ceil(0.07 * C * P * (1-P)), and solves the closed-form quadratic root solver 0.07P_no^2 - 1.07P_no + K >= 0 for guaranteed positive EV cross-venue arbitrage.

Inputs: price, contracts, primary_price, target_roi_pct, +1 more.

get_market_orderbookB

Retrieve normalized Level 2 orderbook depth for Polymarket, Kalshi, Limitless, PredictIt, ForecastEx, and more. Returns top bids, asks, best bid/ask, mid price, spread in basis points (bps), and orderbook imbalance (OBI).

Inputs: market_id (required), depth, venue.

get_whale_tradesB

Query recent block trades and institutional whale orderflow with on-chain wallet addresses, trade sizes, prices, and transaction hashes across Polymarket, Kalshi, and Limitless.

Inputs: limit, venue, market_id, min_size_usd.

scan_arbitrage_opportunitiesA

Find cross-venue matched prediction market arbitrage opportunities (e.g., Polymarket YES vs Kalshi NO, PredictIt vs Polymarket). Calculates exact net ROI, gross edge cents, combined costs, annualized yield, and oracle risk.

Inputs: risk, limit, category, min_net_roi_pct.

search_prediction_marketsA

Search active prediction markets across 7 major venues (Polymarket, Kalshi, Limitless, PredictIt, Drift BET, Smarkets, ForecastEx). Filter by keyword, category, status, or specific venue to view live quotes, volume, and liquidity.

Inputs: query (required), limit, venue, status, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.8/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct action-object pair: orderbook depth, arbitrage scanning, market search, fee math, and whale flow. While orderbook and arbitrage both touch pricing data, the descriptions make the boundaries explicit (raw depth vs. cross-venue opportunity detection). No realistic misselection risk.

    Naming Consistency5/5

    All five tools follow a strict verb_noun snake_case convention: get_market_orderbook, search_prediction_markets, scan_arbitrage_opportunities, calculate_kalshi_fees, get_whale_trades. Verbs are precise and non-redundant across the set.

    Tool Count4/5

    Five tools is a tight, well-scoped set for a multi-venue prediction-market analytics server, with no filler. It is slightly thin relative to the breadth claimed (7 venues), leaving no room for market detail lookup or historical data tools, but nothing extraneous exists.

    Completeness4/5

    The surface covers the core analytical loop: discover markets, inspect depth/pricing, find cross-venue arbitrage, compute venue-specific fees, and track whale flow. Minor gaps remainโ€”no single-market detail-by-id lookup, historical price series, or venue enumerationโ€”which agents can partly work around via search_prediction_markets.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Trade and monitor prediction markets across Polymarket, Kalshi, Opinion, Limitless, and PredictFun from any AI agent. Unified real-time data, live orderbook streaming, and order execution โ€” one API key, one interface, five exchanges.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables smart-money whale and market analytics for Polymarket, including leaderboards, wallet profiles, positions, market clusters, and alerts, through Claude Desktop and other MCP clients.
      6
      902 PyPI
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP-compatible AI agents to research and trade prediction markets on Polymarket and Kalshi, including market search, orderbooks, price history, positions, order routing, and on-chain builder-code attribution, plus overshoot and dispute-risk signals.
      42
      112 PyPI
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to discover and read live prediction markets with their prices, price history and recent trades, view the public leaderboard, and place or cancel limit orders while tracking their own positions. It also installs into Claude Desktop, Claude Code, Cursor or Codex using a local bridge that keeps the API key in a private credentials file instead of command-line arguments.
      31
      MIT