kalshi-mcp-server

📦 PyPI  ·  🗂️ MCP Registry  ·  🐳 Container image  ·  🚀 Deploy guide

A Model Context Protocol server for Kalshi prediction markets. Native RSA-PSS auth, async token-bucket rate limiting, two-step prepare/confirm order flow with safety caps, optional bundled OAuth proxy for remote-MCP deployments, 26 tools + 4 resources across REST and WebSocket. MIT, designed to be forked.

Works with any MCP client — locally via stdio (Claude Desktop, Claude Code, Cursor, Zed, Continue, Cline, Goose, etc.) or remotely as a self-hosted HTTP server (claude.ai custom connectors today, any OAuth-capable MCP client in the future).

⚠️ This software lets an LLM place trades. Read DISCLAIMER.md before deploying. Trading prediction markets involves substantial risk of loss. AI agents make mistakes — sometimes confidently. The authors are not liable for any losses. Test in demo (KALSHI_ENV=demo, KALSHI_TRADING_ENABLED=0) until you understand the failure modes.

Status — alpha. Auth (REST + WS), rate limiting, safety controls, 26 tools across REST + live channels, and 4 resources are in place. A long-lived multiplexed WebSocket session and kalshi://markets/{ticker}/orderbook live resource are planned for v0.2.

Quickstart (30 seconds)

Read-only against Kalshi's demo environment — no real money, no trading flag. This is the safe way to try it.

pipx install kalshi-mcp-server        # or: pip install kalshi-mcp-server

Point any MCP client at it (this is the Claude Desktop / Claude Code shape — see the full client matrix for others):

{
  "mcpServers": {
    "kalshi": {
      "command": "kalshi-mcp",
      "args": ["--env-file", "/Users/you/.kalshi/.env"]
    }
  }
}

Minimal ~/.kalshi/.env (get a demo key at demo.kalshi.co — it's shown once):

KALSHI_API_KEY_ID=<your-demo-key-id>
KALSHI_PRIVATE_KEY_PATH=/absolute/path/to/demo_private_key.pem
KALSHI_ENV=demo

Restart the client and ask it to run a Kalshi tool. Enabling prod and trading is a deliberate opt-in — a few more flags (KALSHI_ALLOW_PROD=1, KALSHI_TRADING_ENABLED=1) — see Configure and the safety model.

What a call looks like

Ask the agent for tradeable markets and kalshi_find_liquid_markets returns a volume-ranked, combo-excluded shortlist (trimmed, illustrative):

{
  "scanned": 300,
  "markets": [
    {
      "ticker": "KXNBAGAME-25JUL12BOSLAL-BOS",
      "title": "Will the Celtics beat the Lakers?",
      "yes_bid_dollars": 0.58, "yes_ask_dollars": 0.60,
      "volume_24h_fp": 41230, "open_interest_fp": 88400,
      "status": "active", "close_time": "2026-07-12T23:30:00Z"
    },
    {
      "ticker": "KXHIGHNY-26JUL12-B90.5",
      "title": "Will NYC's high temp exceed 90.5°F today?",
      "yes_bid_dollars": 0.31, "yes_ask_dollars": 0.34,
      "volume_24h_fp": 12760, "open_interest_fp": 23110,
      "status": "active", "close_time": "2026-07-13T04:00:00Z"
    }
  ]
}

Placing a trade is a deliberate two step — kalshi_prepare_order runs the local safety checks and hands back a confirmation_id; nothing reaches Kalshi until you call kalshi_confirm_order with that token. An LLM can't place an order in a single call.

Why this server

Most existing Kalshi MCPs are thin wrappers around a handful of REST endpoints. This one aims to be:

• Native Kalshi. Real RSA-PSS signer that handles the gotchas (path-without-query-string, ms timestamps, separate demo/prod keys).
• Rate-limit aware. Client-side token bucket mirrors Kalshi's 2026 read/write budget model, so the server can't spam the API into a 429.
• Safe by default. Refuses to start against prod without an explicit opt-in flag. Refuses to write without a separate trading-enabled flag. Order-time controls (size cap, daily cap, cash reserve) are all operator-configurable.
• Hosted-deploy friendly. Accepts the private key as either a file path OR an env var with inline PEM, so it works on platforms without filesystem mounts.
• Fork-able. MIT, no personal data, CI/CD set up so PR contributions flow through main without ever triggering a production deploy — only tagged releases (v*) do. Your fork's deployment stays decoupled from this repo's, and your fork's contributors can't affect what you run.

Install

From PyPI (recommended)

Published as kalshi-mcp-server. pipx installs the kalshi-mcp entrypoint into its own isolated environment:

pipx install kalshi-mcp-server        # or: pip install kalshi-mcp-server

From source

git clone https://github.com/cejor6/kalshi-mcp-server.git
cd kalshi-mcp-server
uv sync

Docker

Multi-arch (amd64 + arm64) images are published to GHCR on every tagged release, tagged :latest and :vX.Y.Z:

docker pull ghcr.io/cejor6/kalshi-mcp-server:latest

See DEPLOY.md for hosted deployment.

Configure

1. Generate a Kalshi API key at https://kalshi.com/account/profile (or the demo equivalent at https://demo.kalshi.co/account/profile). Save the private key — it is shown ONCE.

2. Put your secrets in one .env file. A good location for the MCP-client use case is ~/.kalshi/.env (outside any repo). For local dev, the repo's own .env (gitignored) works too.

cp .env.example ~/.kalshi/.env
# edit ~/.kalshi/.env

3. At minimum, set:

KALSHI_API_KEY_ID=<your-key-id>
KALSHI_PRIVATE_KEY_PATH=/absolute/path/to/your_kalshi_private_key.pem
KALSHI_ENV=demo

For prod, also set:

KALSHI_ENV=prod
KALSHI_ALLOW_PROD=1
KALSHI_TRADING_ENABLED=1   # only if you want writes

How env vars are resolved

On startup, the server resolves config in this order (highest wins):

1. Values already in the process environment — set in the MCP client config's env: block, or exported in your shell.
2. .env file — loaded from --env-file PATH if you pass that flag, otherwise from ./.env in the current working directory if it exists. Variables already in the environment from step 1 are not overridden.

So you can put secrets either inline in the MCP config (env:) or in a file the config points at (--env-file). You don't need to do both.

Use with an MCP client (stdio)

Every MCP stdio client uses the same shape: a command to launch the server, optional args, optional env. The differences are just the file/UI where you put the config.

Three install patterns work — pick whichever fits your environment.

Pattern A — pipx install (cleanest, recommended)

Installs kalshi-mcp to a globally-available, isolated environment. pipx is the modern Python tool for this:

pipx install kalshi-mcp-server

MCP client config then collapses to:

{
  "mcpServers": {
    "kalshi": {
      "command": "kalshi-mcp",
      "args": ["--env-file", "/Users/you/.kalshi/.env"]
    }
  }
}

Update with pipx upgrade kalshi-mcp-server when you want the latest.

Pattern B — uv run against a local clone

Best if you've cloned the repo and have uv installed. Point the MCP client at uv with --directory:

{
  "mcpServers": {
    "kalshi": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/kalshi-mcp-server",
        "kalshi-mcp",
        "--env-file", "/Users/you/.kalshi/.env"
      ]
    }
  }
}

uv run activates the project's venv automatically. Update with git pull + restart the MCP client. Useful for development / hacking on the server itself.

Pattern C — Docker against the public image

Best for users without Python installed, or who prefer container isolation:

{
  "mcpServers": {
    "kalshi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/you/.kalshi/demo.pem:/secrets/demo.pem:ro",
        "-e", "KALSHI_API_KEY_ID=<your-key-id>",
        "-e", "KALSHI_PRIVATE_KEY_PATH=/secrets/demo.pem",
        "-e", "KALSHI_ENV=demo",
        "ghcr.io/cejor6/kalshi-mcp-server:latest"
      ]
    }
  }
}

The -v mount bind-mounts your PEM file read-only into the container; KALSHI_PRIVATE_KEY_PATH points at that path. Secrets live in the JSON config — fine for a single-user machine.

Where to put this config: