# kalshi-mcp-server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP Version](https://img.shields.io/badge/MCP%20Spec-2024--11--05-success.svg)](https://spec.modelcontextprotocol.io/)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![Tests](https://img.shields.io/badge/tests-39%20passed%20(100%25)-brightgreen.svg)](https://github.com/nexosdata/kalshi-mcp-server)
[![Runtime Dependencies](https://img.shields.io/badge/dependencies-0%20runtime-orange.svg)](https://www.npmjs.com/package/kalshi-mcp-server)

> 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$.

---

## Architecture Overview

```mermaid
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`](#1-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`](#2-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`](#3-kalshi_market_search) | `query`, `category`, `status`, `limit` | Searches Kalshi prediction markets across Economics, Politics, Financials, Climate, and Tech & Culture. |
| [`kalshi_implied_probability`](#4-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`](#5-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
```bash
npx kalshi-mcp-server --help
```

### 2. Inspect Available Tools
```bash
npx kalshi-mcp-server --tools
```

### 3. Test an MCP Tool from CLI
```bash
# 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`

```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:

```json
{
  "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`):

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

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

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

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

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

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

```bash
# 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](file:///Users/viliamgonda/Desktop/arbitragepolyibkrbot/open_source_repos/kalshi-mcp-server/LICENSE) for full details.