Kalshi MCP Server

Give Claude access to Kalshi prediction markets — browse live odds, analyze price history, and trade YES/NO contracts.

Built on the Model Context Protocol (MCP), this server connects Claude (and any MCP-compatible AI) directly to the Kalshi Trade API v2.

First MCP server for Kalshi. Ask Claude "What are the current odds on the Fed rate decision?" and get a live answer.

---

Features

Tool	Description	Tier
get_markets	Browse open/settled markets with filters	🆓 Free
get_market_details	Live odds, volume, order book for a market	🆓 Free
get_market_price_history	OHLC candlestick data (1-min, hourly, daily)	🆓 Free
get_portfolio	Account balance and open positions	🔑 Pro
place_order	Buy YES/NO contracts (dry-run confirmation)	🔑 Pro
get_order_history	Fills, settlements, open orders	🔑 Pro

---

Quick Start

1. Install

git clone https://github.com/shadowfax-mitch/kalshi-mcp-server
cd kalshi-mcp-server
pip install -r requirements.txt

Or install as a package:

pip install kalshi-mcp-server

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Free Tier (read-only, no credentials needed)

{
  "mcpServers": {
    "kalshi": {
      "command": "python",
      "args": ["-m", "kalshi_mcp.server"],
      "cwd": "/path/to/kalshi-mcp-server"
    }
  }
}

Pro Tier (full trading access)

{
  "mcpServers": {
    "kalshi": {
      "command": "python",
      "args": ["-m", "kalshi_mcp.server"],
      "cwd": "/path/to/kalshi-mcp-server",
      "env": {
        "KALSHI_API_KEY": "your-api-key-uuid",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/private_key.pem"
      }
    }
  }
}

Pro Tier (with package install / pipx)

{
  "mcpServers": {
    "kalshi": {
      "command": "kalshi-mcp",
      "env": {
        "KALSHI_API_KEY": "your-api-key-uuid",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/private_key.pem"
      }
    }
  }
}

3. Restart Claude Desktop

After saving the config, restart Claude Desktop. You'll see a 🔨 tools icon — click it to verify Kalshi tools are loaded.

---

Getting Kalshi API Credentials (Pro Tier)

1. Go to https://kalshi.com/account/settings
2. Navigate to API → Create API Key
3. Download your RSA private key PEM file
4. Copy your API key UUID
5. Set both as environment variables (see config above)

Security: Never commit your private key or API key to version control.
Store them securely — they provide full trading access to your account.

---

Usage Examples

Once configured, talk to Claude naturally:

Browse Markets

"Show me open BTC prediction markets"
→ get_markets(series_ticker="KXBTC15M")

"What are the most liquid markets right now?"
→ get_markets(status="open", limit=20)

"Show me recently settled markets"
→ get_markets(status="settled", limit=10)

Market Research

"Get the full details for KXBTC15M-24NOV1913-T10000 including the order book"
→ get_market_details("KXBTC15M-24NOV1913-T10000")

"Show me the hourly price chart for this market over the last 48 hours"
→ get_market_price_history("KXBTC15M-...", period_interval=60, lookback_hours=48)

"Get 1-minute candles for the last hour"
→ get_market_price_history("...", period_interval=1, lookback_hours=1)

Portfolio (Pro)

"What's my current balance and positions?"
→ get_portfolio()

"Show me my recent trades and P&L"
→ get_order_history(include_fills=True, include_settlements=True)

Trading (Pro)

Claude automatically uses a dry-run confirmation flow:

"Buy 10 YES contracts on KXBTC15M-... at 65 cents"

Claude:
1. Calls place_order(..., dry_run=True)  ← preview
2. Shows you:
   📋 ORDER PREVIEW (not submitted):
     Ticker:         KXBTC15M-24NOV1913-T10000
     Side:           YES
     Contracts:      10
     Limit price:    65¢ ($0.65)
     Estimated cost: $6.50
     Max payout:     $10.00
     Max profit:     $3.50

3. Asks: "Shall I submit this order?"
4. On confirmation: calls place_order(..., dry_run=False)

---

Tool Reference

get_markets

List Kalshi prediction markets.

Parameter	Type	Default	Description
status	str	"open"	"open", "closed", or "settled"
series_ticker	str		Filter by series (e.g. "KXBTC15M", "NASDAQ100D")
event_ticker	str		Filter by event
limit	int	20	Results per page (max 200)
cursor	str		Pagination cursor

---

get_market_details

Full detail for a single market including live order book.

Parameter	Type	Default	Description
ticker	str	required	Market ticker
include_orderbook	bool	true	Fetch live order book

---

get_market_price_history

OHLC candlestick price history.

Parameter	Type	Default	Description
ticker	str	required	Market ticker
period_interval	int	60	Candle size in minutes: 1, 60, or 1440
lookback_hours	int	24	Hours of history (1–168)

---

get_portfolio (Pro)

Account balance and open positions. No parameters.

---

place_order (Pro)

Place a limit buy order.

Parameter	Type	Default	Description
ticker	str	required	Market ticker
side	str	required	"yes" or "no"
count	int	required	Number of contracts
price_cents	int	required	Limit price in cents (1–99)
dry_run	bool	true	Preview without submitting (always start here)

Pricing guide:

• Each contract pays $1.00 if you're correct, $0.00 if wrong
• price_cents=65 means you pay 65¢ and profit 35¢ if correct
• price_cents reflects the market's implied probability (65¢ ≈ 65% chance)

---

get_order_history (Pro)

Recent trading activity.

Parameter	Type	Default	Description
include_fills	bool	true	Recent executed trades
include_settlements	bool	true	Settled contracts with P&L
include_open_orders	bool	true	Resting limit orders
ticker	str		Filter to specific market
limit	int	25	Records per section

---

Architecture

Claude Desktop
    │
    │  MCP (stdio)
    ▼
kalshi_mcp/server.py      ← FastMCP server, tool definitions, formatting
    │
    ▼
kalshi_mcp/client.py      ← Kalshi REST API client (httpx)
    │
    ▼
kalshi_mcp/auth.py        ← RSA-PSS signing (Kalshi API v2 auth scheme)
    │
    ▼
https://api.elections.kalshi.com/trade-api/v2

Auth scheme (RSA-PSS):

Signature = RSA-PSS(
    message  = f"{unix_timestamp}{METHOD}{/trade-api/v2/endpoint}",
    hash     = SHA-256,
    mgf      = MGF1(SHA-256),
    salt_len = 32
)

Headers:
  KALSHI-ACCESS-KEY       = api_key_uuid
  KALSHI-ACCESS-SIGNATURE = base64(signature)
  KALSHI-ACCESS-TIMESTAMP = unix_timestamp_seconds

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type check
mypy kalshi_mcp/

# Lint
ruff check kalshi_mcp/

# Test the server manually (stdio transport)
python -m kalshi_mcp.server

Project Structure

kalshi-mcp-server/
├── kalshi_mcp/
│   ├── __init__.py      # Package metadata
│   ├── server.py        # MCP server & tool definitions
│   ├── client.py        # Kalshi API client
│   └── auth.py          # RSA-PSS authentication
├── tests/
│   └── test_client.py   # Unit tests
├── README.md
├── requirements.txt
├── pyproject.toml
└── .env.example

---

Pricing & Tiers

🆓 Free Tier

• Market browsing — search and filter thousands of markets
• Live odds — real-time YES/NO prices and order books
• Price history — OHLC candlestick data for any market
• No API credentials required

🔑 Pro Tier

Everything in Free, plus:

• Portfolio view — balance, positions, unrealized P&L
• Order placement — buy YES/NO contracts with confirmation flow
• Order history — fills, settlements, open orders

Available at: PaidMCP | GitHub Sponsors

---

Security

• Never trade with funds you can't afford to lose. Prediction markets carry real financial risk.
• Store your API key and private key securely. Never commit them to version control.
• The place_order tool defaults to dry_run=True — orders require explicit confirmation.
• Consider setting position size limits at the Kalshi account level as an extra safeguard.

---

Troubleshooting

"Auth init failed (free-tier only)"
→ Check that KALSHI_API_KEY is a valid UUID and KALSHI_PRIVATE_KEY_PATH points to your PEM file.

"Kalshi API 401"
→ Your key may be expired or revoked. Regenerate at kalshi.com/account/settings.

"Kalshi API 403"
→ You may be trying a pro feature without valid credentials, or your account may be restricted.

Tools not showing in Claude Desktop
→ Verify the cwd path in your config. Restart Claude Desktop after any config change.

"period_interval must be 1, 60, or 1440"
→ Kalshi only supports these candle sizes. Use 1 (minute), 60 (hourly), or 1440 (daily).

---

Contributing

Pull requests welcome! Please open an issue first for significant changes.

git clone https://github.com/shadowfax-mitch/kalshi-mcp-server
cd kalshi-mcp-server
pip install -e ".[dev]"
pytest tests/

---

License

MIT License — see LICENSE

---

Disclaimer

This is an unofficial third-party tool. It is not affiliated with, endorsed by, or sponsored by Kalshi Inc. Use of the Kalshi API is subject to Kalshi's Terms of Service. Trading prediction markets involves financial risk.