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)

Go to https://kalshi.com/account/settings
Navigate to API → Create API Key
Download your RSA private key PEM file
Copy your API key UUID
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.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
kalshi_mcp		kalshi_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Kalshi MCP Server

Features

Quick Start

1. Install

2. Configure Claude Desktop

Free Tier (read-only, no credentials needed)

Pro Tier (full trading access)

Pro Tier (with package install / pipx)

3. Restart Claude Desktop

Getting Kalshi API Credentials (Pro Tier)

Usage Examples

Browse Markets

Market Research

Portfolio (Pro)

Trading (Pro)

Tool Reference

get_markets

get_market_details

get_market_price_history

get_portfolio (Pro)

place_order (Pro)

get_order_history (Pro)

Architecture

Development

Project Structure

Pricing & Tiers

🆓 Free Tier

🔑 Pro Tier

Security

Troubleshooting

Contributing

License

Disclaimer

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`get_markets`

`get_market_details`

`get_market_price_history`

`get_portfolio` (Pro)

`place_order` (Pro)

`get_order_history` (Pro)

Packages