polymarket-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@polymarket-mcp-server find arbitrage opportunities between Polymarket and Kalshi"
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 ๐ฎโก
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:
Level 2 Normalized Depth: Real-time bid/ask ladders, mid-prices, basis point spreads, and Order Book Imbalance (OBI).
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.
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.Institutional Whale Orderflow: Live tape monitoring large block fills (> $5,000, > $50,000, > $100,000) with on-chain wallet addresses and Polygon transaction hashes.
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, andtools/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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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_KEYis 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:
polymarketType:
commandCommand:
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 |
|
| Yes | โ | Market identifier, token condition ID, or venue slug |
|
| No |
|
|
|
| No |
| 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 |
|
| No |
| Filter: |
|
| No |
| Minimum net ROI percentage after exchange taker fees and gas |
|
| No |
| Oracle risk filter: |
|
| No |
| 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 |
|
| No |
| Number of contracts to trade |
|
| No | โ | Kalshi contract price [0.01 - 0.99] for direct fee calculation |
|
| No | โ | Primary leg price (e.g. Polymarket YES at 0.46) to solve breakeven |
|
| No |
| 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 |
|
| No |
|
|
|
| No | โ | Filter by specific market identifier or slug |
|
| No |
| Minimum trade notional size in USD |
|
| No |
| 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 |
|
| Yes | โ | Search term (e.g., |
|
| No |
| Venue filter or |
|
| No | โ | Filter by category ( |
|
| No |
|
|
|
| No |
| 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:
Obtain an API key from naxosdata.com.
Set the environment variable:
export NAXOS_API_KEY="nx_live_your_api_key_here"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 testTest 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 toolscalculate_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
Scored across 5 tools
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.
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.
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.
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
AI prediction market trading โ real-time data, CLOB exchange, Prop Desk, 40+ tools
Order-book depth & history for Polymarket, Kalshi & Limitless. Keyless demo, key for full access.
Prediction market discovery, classification, pricing, open interest and volume across venues.
Cross-venue prediction market routing for AI agents with arbitrage, quotes, history, and signals.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceTrade 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.-

orcalayer-mcpofficial
AlicenseAqualityBmaintenanceEnables smart-money whale and market analytics for Polymarket, including leaderboards, wallet profiles, positions, market clusters, and alerts, through Claude Desktop and other MCP clients.6902 PyPI1MIT- AlicenseBqualityBmaintenanceEnables 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.42112 PyPI1MIT

Problee MCPofficial
AlicenseBqualityCmaintenanceEnables 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.31MIT