kalshi-mcp

A TypeScript Model Context Protocol (MCP) server that lets an AI agent fully interface with Kalshi — the regulated events/prediction exchange. It exposes Kalshi's Trade API v2 as MCP tools over stdio: market data, portfolio, full order management, structural data, RFQ/quotes, and live WebSocket snapshots.

ℹ️ Unofficial. Community project, not affiliated with or endorsed by Kalshi. "Kalshi" is a trademark of its owner.

⚠️ Real money. Kalshi production is a real-money exchange. This server defaults to the demo (paper) environment and gates all trading behind explicit, layered safety rails (see Safety). You are responsible for any orders an agent places once you enable trading and point it at production.

Quick start (from npm)

No clone or build needed — your MCP client runs it via npx:

{
  "mcpServers": {
    "kalshi": {
      "command": "npx",
      "args": ["-y", "kalshi-mcp"],
      "env": {
        "KALSHI_ENV": "demo",
        "KALSHI_API_KEY_ID": "your-key-id",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/kalshi_key.pem"
      }
    }
  }
}

Public market-data tools work with no credentials. See Configuration for the full env list and Safety before enabling trading.

Features

| Toolset | Tools | Auth | |---|---|---| | market_data | get_exchange_status, get_exchange_schedule, get_exchange_announcements, get_series_list, get_series, get_events, get_event, get_markets, get_market, get_market_orderbook, get_trades, get_market_candlesticks, get_series_fee_changes | public | | portfolio | get_balance, get_positions, get_fills, get_settlements, get_user_data_timestamp | required | | orders | get_orders, get_order, create_order, cancel_order, amend_order, decrease_order, batch_create_orders, batch_cancel_orders, get_order_queue_position, get_queue_positions, get_total_resting_order_value | required | | structural | get_multivariate_event_collections, get_multivariate_event_collection, create_market_in_multivariate_event_collection, get_milestones, get_milestone, get_structured_targets, get_structured_target | mostly public | | communications (opt-in) | RFQ + quotes: get_rfqs, get_rfq, create_rfq, delete_rfq, get_quotes, get_quote, create_quote, accept_quote, confirm_quote, delete_quote, get_communications_id | required (members-only) | | streaming | ws_orderbook_snapshot, ws_ticker_snapshot, ws_await_fill, ws_collect_trades | required (signed WS) |

Default toolsets: market_data, portfolio, orders, structural, streaming (~40 tools). communications is opt-in.

Prerequisites

• Node.js ≥ 20 (uses native fetch).
• A Kalshi account + API key only if you want authenticated tools. Public market-data tools work with no credentials.

Install & build

npm install
npm run build      # compiles src → dist
npm test           # unit tests (auth signing, client, safety)
npm run smoke      # live DEMO public-endpoint check (no credentials needed)

Creating a Kalshi API key

1. Log in to Kalshi → Account → API Keys (use the demo site for paper trading: demo.kalshi.co).
2. Create a key. Kalshi shows you a Key ID (UUID-like) and lets you download the RSA private key (PEM) once — save it; it cannot be retrieved again.
3. Demo and production are separate environments with separate keys.

Configuration

Copy .env.example → .env and fill in. All variables:

| Variable | Default | Purpose | |---|---|---| | KALSHI_ENV | demo | demo (paper) or prod (real money). | | KALSHI_ALLOW_PRODUCTION | false | Must be true and KALSHI_ENV=prod to use production, else the server refuses to start. | | KALSHI_API_KEY_ID | — | Your Kalshi Key ID. | | KALSHI_PRIVATE_KEY_PATH | — | Path to the RSA private-key PEM. | | KALSHI_PRIVATE_KEY_PEM | — | Inline PEM alternative (supports \n escapes). | | KALSHI_TRADING_ENABLED | false | Master switch — order-mutating tools are blocked until true. | | KALSHI_MAX_ORDER_CONTRACTS | 100 | Reject orders exceeding this contract count (batches summed). | | KALSHI_MAX_ORDER_COST_CENTS | 10000 | Reject orders whose estimated cost exceeds this (¢). | | KALSHI_TOOLSETS | market_data,portfolio,orders,structural,streaming | Comma list, or all. Trims the tool surface. | | KALSHI_WS_TIMEOUT_MS | 5000 | WebSocket snapshot timeout (hard-capped at 15000). | | KALSHI_MAX_RETRIES | 4 | Retries on 429 / transient 5xx (exponential backoff + jitter). |

Running with an MCP client

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json)

{
  "mcpServers": {
    "kalshi": {
      "command": "node",
      "args": ["/absolute/path/to/bot-trader/dist/index.js"],
      "env": {
        "KALSHI_ENV": "demo",
        "KALSHI_API_KEY_ID": "your-key-id",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/kalshi_private_key.pem",
        "KALSHI_TRADING_ENABLED": "false"
      }
    }
  }
}

Run npm run build first so dist/index.js exists. For local development without building, use "command": "npx", "args": ["tsx", "/absolute/path/to/bot-trader/src/index.ts"].

Inspect the tools

npm run inspect   # builds, then launches the MCP Inspector against dist/index.js

Safety

Trading is protected by five independent layers:

1. Environment double-gate — prod requires both KALSHI_ENV=prod and KALSHI_ALLOW_PRODUCTION=true, or startup fails. Default is demo.
2. Trading switch — KALSHI_TRADING_ENABLED=false blocks every order-mutating tool with a clear message; reads/market-data still work.
3. Size guards — per-order and per-batch limits on contract count and estimated cost.
4. Dry run — create_order and batch_create_orders accept dry_run: true to validate + preview the exact payload without sending.
5. Honest annotations — order tools carry MCP destructiveHint, so a host like Claude can prompt for confirmation.

Prices are integer cents (1–99); quantities are whole contracts; query/body timestamps are Unix seconds.

Development

src/
  index.ts          # stdio entrypoint
  config.ts         # env parsing + demo/prod gate
  server.ts         # McpServer assembly
  safety.ts         # trading guards
  kalshi/           # auth (RSA-PSS signing), HTTP client, WebSocket snapshot helper, errors, types
  tools/            # one module per toolset (market-data is the exemplar)
  util/             # shared zod fragments + result helpers + formatting
test/               # node:test unit tests
scripts/smoke.ts    # no-credential live demo check

• npm run typecheck — tsc --noEmit.
• npm test — unit tests via the Node test runner (tsx loader).

Notes & limitations

• Authentication uses Kalshi's RSA-PSS request signing (verified against Kalshi's official starter code). The legacy email/password login is deprecated and not supported.
• WebSocket tools take a single-shot snapshot (connect → subscribe → capture → close); persistent background subscriptions are out of scope for v1.
• Remote (Streamable HTTP) transport is not included — this is a local stdio server.

Disclaimer

This software is provided as-is, with no warranty. It is not financial advice. Trading on Kalshi involves risk of loss. Verify every order before enabling live trading.