Skip to main content
Glama
kalshi-mcp-server

kalshi-mcp-server

by nexosdata

kalshi-mcp-server

License: MIT MCP Version Node.js Version Tests Runtime Dependencies

Production-ready Model Context Protocol (MCP) server for Kalshi CFTC-regulated prediction markets. Empowers Claude Desktop, Cursor IDE, Windsurf, and quantitative AI agents to query live Level 2 orderbook depth, calculate exact CFTC Rule 40.2 taker fees, solve quadratic arbitrage breakevens, calculate implied probabilities and scenario yields, and scan cross-venue pricing spreads against Polymarket.


Targeted Keywords & Highlights

  • kalshi mcp server – Native JSON-RPC 2.0 stdio transport adhering to MCP 2024-11-05.

  • model context protocol kalshi – Real-time event contracts: Fed funds rate cuts, CPI prints, S&P 500, weather, and presidential politics.

  • claude kalshi tool – Instant copy-paste Claude Desktop integration with one-click terminal launcher.

  • cursor kalshi mcp – Full IDE context for Cursor AI agents scanning prediction market microstructure.

  • cftc prediction market mcp – Exact regulatory clearing math with Rule 40.2 taker fees: $\lceil 0.07 \cdot C \cdot P \cdot (1 - P) \rceil$.


Related MCP server: oddsrail

Architecture Overview

flowchart TD
    subgraph Clients["Client Environments"]
        CD["Claude Desktop (macOS / Win / Linux)"]
        CU["Cursor IDE / Windsurf / VS Code"]
        AI["Autonomous AI Trading Agent"]
    end

    subgraph Server["kalshi-mcp-server (stdio JSON-RPC 2.0)"]
        TR["Transport Decoder<br/>(Newline-Delimited & Content-Length)"]
        RT["Router & MCP Dispatcher<br/>(Spec 2024-11-05)"]
        
        subgraph Tools["Tool Engine"]
            T1["kalshi_orderbook<br/>(L2 Depth & OBI)"]
            T2["kalshi_fee_calculator<br/>(CFTC Rule 40.2 & Quadratic Solver)"]
            T3["kalshi_market_search<br/>(Economics, Politics, Financials, Climate)"]
            T4["kalshi_implied_probability<br/>(Yields, Scenarios & Kelly Sizing)"]
            T5["kalshi_cross_spread<br/>(Kalshi vs Polymarket Box Spreads)"]
        end

        GW["NaxosData Gateway Client & Microstructure Provider"]
    end

    subgraph Liquidity["Prediction Market Liquidity"]
        ND["NaxosData Institutional API Gateway<br/>(api.naxosdata.com)"]
        PUB["Kalshi Public API v2<br/>(Direct Web Fallback)"]
        SIM["Normalized Microstructure Fallback Engine"]
    end

    CD -->|stdio JSON-RPC| TR
    CU -->|stdio JSON-RPC| TR
    AI -->|stdio JSON-RPC| TR

    TR --> RT
    RT --> T1
    RT --> T2
    RT --> T3
    RT --> T4
    RT --> T5

    T1 --> GW
    T2 --> GW
    T3 --> GW
    T4 --> GW
    T5 --> GW

    GW -->|Bearer Auth| ND
    GW -.->|Public HTTP| PUB
    GW -.->|Deterministic Offline| SIM

Available MCP Tools

Tool Name

Parameters

Description

kalshi_orderbook

ticker (req), depth

Fetches live Level 2 depth, bid/ask spread in cents, top-5 depth, and Order Book Imbalance (OBI) for Kalshi contracts.

kalshi_fee_calculator

contracts, price, primary_price, target_roi_pct, primary_fee_cents

Calculates statutory CFTC Rule 40.2 taker fees and solves closed-form quadratic breakeven prices for cross-venue arbitrage.

kalshi_market_search

query, category, status, limit

Searches Kalshi prediction markets across Economics, Politics, Financials, Climate, and Tech & Culture.

kalshi_implied_probability

price (req), outcome, contracts, settlement_days, subjective_prob_pct, bankroll_usd

Calculates market-implied probabilities, gross & net payout yields, scenario matrices, and Kelly criterion allocation.

kalshi_cross_spread

ticker, category, min_net_roi_pct, limit

Queries cross-venue price spreads and dual-leg arbitrage between Kalshi and Polymarket with exact fee deductions.


Quickstart

1. Instant Run via NPX

npx kalshi-mcp-server --help

2. Inspect Available Tools

npx kalshi-mcp-server --tools

3. Test an MCP Tool from CLI

# Level 2 orderbook for December 2026 Fed Funds Rate Cut
npx kalshi-mcp-server --test-call kalshi_orderbook '{"ticker":"FED-26DEC","depth":5}'

# Compute CFTC fees & solve quadratic breakeven against a 44¢ Polymarket leg
npx kalshi-mcp-server --test-call kalshi_fee_calculator '{"contracts":100,"price":52,"primary_price":44,"target_roi_pct":2.5}'

# Search active climate & weather contracts
npx kalshi-mcp-server --test-call kalshi_market_search '{"category":"Climate"}'

# Calculate implied probability and Kelly sizing for a 55¢ contract
npx kalshi-mcp-server --test-call kalshi_implied_probability '{"price":55,"settlement_days":45,"subjective_prob_pct":65,"bankroll_usd":25000}'

# Scan cross-venue spreads with Polymarket
npx kalshi-mcp-server --test-call kalshi_cross_spread '{"min_net_roi_pct":1.0}'

Configuration Guides

Claude Desktop Setup

Add the server definition to 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

{
  "mcpServers": {
    "kalshi": {
      "command": "npx",
      "args": ["-y", "kalshi-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Cursor IDE Setup

Add the server entry to .cursor/mcp.json in your project root or workspace:

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

Windsurf & Continue Setup

For Windsurf (~/.codeium/windsurf/mcp_config.json) or Continue (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "kalshi",
      "command": "npx",
      "args": ["-y", "kalshi-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here"
      }
    }
  ]
}

Deep Dive: Tool Documentation & Usage

1. kalshi_orderbook

Fetches normalized Level 2 orderbook depth, bid/ask spread in cents, and Order Book Imbalance (OBI).

{
  "ticker": "FED-26DEC",
  "depth": 5
}

Key Response Fields:

  • best_bid_cents / best_ask_cents: Top of book quoted in integer cents ($0.01 - $0.99).

  • spread_cents: Tightness of the market in cents.

  • obi_top5: Order Book Imbalance across top-5 levels: $$\text{OBI} = \frac{V_{\text{bid}} - V_{\text{ask}}}{V_{\text{bid}} + V_{\text{ask}}}$$

  • top5_depth_contracts: Aggregated contract liquidity across top 5 price steps.

  • estimated_cftc_fee_cents: Statutory fee for a baseline order of 100 contracts at mid price.


2. kalshi_fee_calculator

Calculates statutory CFTC Rule 40.2 taker fees and solves closed-form quadratic breakeven prices for cross-venue matched trades.

{
  "contracts": 100,
  "price": 52,
  "primary_price": 44,
  "target_roi_pct": 2.5,
  "primary_fee_cents": 0.8
}

Statutory Regulatory Fee Schedule (CFTC Rule 40.2)

Kalshi operates as a Designated Contract Market (DCM) regulated by the US Commodity Futures Trading Commission (CFTC). The standard exchange taker fee formula is: $$\text{Fee} = \left\lceil 0.07 \cdot C \cdot P \cdot (1 - P) \right\rceil$$ Where:

  • $C$ is the number of event contracts.

  • $P$ is the contract price in dollars ($0.01 \le P \le 0.99$).

  • $\lceil \cdot \rceil$ is the ceiling operator rounding up to the nearest whole integer cent ($0.01) per trade order.

Quadratic Breakeven Formulation

When executing cross-venue matched pairs (e.g. Polymarket YES at price $P_1$ with fee $F_1$, paired with Kalshi NO at price $P_2$), achieving a target net return on investment $R$ requires: $$P_1 + \frac{F_1}{C} + P_2 + \frac{\text{Fee}_{\text{Kalshi}}(C, P_2)}{C} \le \frac{1}{1 + R}$$

Approximating the continuous fee bound yields the quadratic inequality: $$0.07 P_2^2 - 1.07 P_2 + K \ge 0$$ $$\text{where } K = \frac{1}{1 + R} - P_1 - \frac{F_1}{C}$$

The solver computes the analytic root $P_2^* = \frac{1.07 - \sqrt{1.1449 - 0.28 K}}{0.14}$ and verifies it against the discrete ceiling step-function.


3. kalshi_market_search

Discovers active and settled event contracts across Kalshi's institutional categories.

{
  "query": "CPI",
  "category": "Economics",
  "status": "ACTIVE",
  "limit": 5
}

Supported Categories:

  • Economics: Fed interest rates, CPI headline & core inflation, non-farm payrolls, GDP, recession.

  • Politics: Presidential elections, congressional control, approvals, judicial appointments.

  • Financials: S&P 500 year-end closes, Nasdaq 100, 10-Year Treasury Yields, commodity strikes.

  • Climate: Daily maximum temperatures (NYC, Miami, Chicago, Austin), snowfall records, hurricane landfalls.

  • Tech & Culture: Frontier AI benchmarks (ARC-AGI), spaceflight launches, regulatory actions.


4. kalshi_implied_probability

Transforms quoted market prices into probability distributions, scenario payoffs, and optimal bet sizing.

{
  "price": 55,
  "outcome": "YES",
  "contracts": 100,
  "settlement_days": 45,
  "subjective_prob_pct": 65,
  "bankroll_usd": 25000
}

Output Features:

  • Raw Implied Probability: Directly implied by the market price ($P \times 100$%, e.g., 0.62 = 62.0%).

  • Spread & Fee Adjusted Break-Even Win Rate: Minimum probability required to overcome CFTC Rule 40.2 taker drag.

  • Annualized APY Yield: Net holding yield annualized over event duration.

  • Kelly Criterion Optimal Sizing: $$f^* = \frac{b \cdot p - q}{b}$$ Recommends both full Kelly fraction and half-Kelly position sizing in USD to safeguard bankroll against downside variance.


5. kalshi_cross_spread

Scans matched events across Kalshi and Polymarket, identifying pricing discrepancies and net arbitrage edge.

{
  "category": "Economics",
  "min_net_roi_pct": 0.5,
  "limit": 10
}

Evaluation Pipeline:

  1. Aligns dual-venue order books for equivalent resolution terms.

  2. Evaluates dual-box legs:

    • Strategy A: Buy Kalshi YES + Buy Polymarket NO.

    • Strategy B: Buy Polymarket YES + Buy Kalshi NO.

  3. Automatically deducts Kalshi Rule 40.2 taker fee and Polygon L2 order execution gas.

  4. Assesses Oracle Resolution Divergence (e.g. Kalshi BLS / Fed statistical releases vs. Polymarket UMA Optimistic Oracle).


Environment Variables

Variable

Type

Default

Description

NAXOS_API_KEY

String

Optional

Your NaxosData API key (nx_live_... or nx_pro_...) for institutional Level 2 feeds.

NAXOS_BASE_URL

String

https://api.naxosdata.com

API Gateway endpoint.

LOG_LEVEL

String

info

Logging verbosity on STDERR (debug, info, warn, error).

DEBUG

Boolean

false

Enables full JSON-RPC payload logging on STDERR.


Local Development & Testing

This project has zero production runtime dependencies and uses Node.js native fetch and standard library streams.

# 1. Clone repository
git clone https://github.com/nexosdata/kalshi-mcp-server.git
cd kalshi-mcp-server

# 2. Install dev dependencies (TypeScript & @types/node)
npm install

# 3. Build TypeScript to dist/
npm run build

# 4. Run automated test suite (39 tests)
npm test

# 5. Typecheck
npm run typecheck

License

MIT License. Copyright (c) 2026 NaxosData Contributors & William Gonda. See LICENSE for full details.

Available Tools

5 tools
kalshi_cross_spreadA

Queries live cross-venue spreads, pricing divergences, and dual-leg arbitrage opportunities between Kalshi and Polymarket contracts, with exact CFTC fee and Polygon gas deductions.

Inputs: limit, ticker, category, min_net_roi_pct.

kalshi_fee_calculatorB

Calculates CFTC Rule 40.2 exchange taker fees for Kalshi contracts and solves closed-form quadratic breakeven prices for cross-venue arbitrage pairs.

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

kalshi_implied_probabilityB

Calculates market implied probability, gross & net payout yields, event scenario outcomes (YES win vs NO win), and Kelly criterion sizing for Kalshi contracts.

Inputs: price (required), outcome, contracts, bankroll_usd, +2 more.

kalshi_orderbookB

Fetches live Level 2 orderbook depth, bid/ask spread in cents, top-5 depth, and Order Book Imbalance (OBI) for Kalshi CFTC-regulated contracts (Fed funds rates, CPI inflation, elections, weather).

Inputs: ticker (required), depth.

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

    Disambiguation4/5

    Each tool targets a clearly different function: orderbook depth, market search, fee calculation, probability/Kelly analytics, and cross-venue arbitrage. There is minor conceptual overlap between fee/breakeven calculations and cross-spread arbitrage economics, but the descriptions make the boundaries mostly clear.

    Naming Consistency5/5

    All tools use a consistent kalshi_ prefix followed by a descriptive noun phrase. Although the names are noun-oriented rather than verb_noun, the convention is uniform and predictable across the entire set.

    Tool Count5/5

    Five tools is well within the ideal range for a focused analytics server. Each tool covers a distinct part of the Kalshi market-analysis workflow without unnecessary surface area.

    Completeness4/5

    The surface covers search, orderbook depth, fee modeling, implied probability/Kelly sizing, and cross-venue arbitrage, which are the core analytics for this domain. Minor gaps exist around fetching a single market by ticker or accessing historical price data, but the main workflows are supported.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Prediction market probability oracle for AI agents. 26 tools across 500+ live markets from Kalshi and Polymarket. Cross-source arbitrage detection, structured TPF signals, Kelly Criterion sizing, agent performance tracking, and webhook alerts.
      9
      70 npm
      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
    • A
      license
      A
      quality
      C
      maintenance
      Connects Claude Desktop, Cursor, Windsurf, and autonomous agents to live prediction-market Level 2 orderbooks, cross-venue arbitrage scanning, quadratic fee calculations, whale trade monitoring, and multi-venue market search across seven venues.
      5
      MIT