Kalshi Prediction Markets

kalshi-mcp-server

📦 [PyPI](https://pypi.org/project/kalshi-mcp-server/) · 🗂️ [MCP Registry](https://registry.modelcontextprotocol.io/?search=io.github.cejor6/kalshi-mcp-server) · 🐳 [Container image](https://github.com/cejor6/kalshi-mcp-server/pkgs/container/kalshi-mcp-server) · 🚀 [Deploy guide](DEPLOY.md)

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.

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

1. 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= ", "-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:

If you'd rather inline secrets in the MCP config (acceptable for local dev where the config file is on your own machine):

{

"mcpServers": { "kalshi": { "command": "kalshi-mcp", "env": { "KALSHI_API_KEY_ID": "your-key-id", "KALSHI_PRIVATE_KEY_PATH": "/path/to/your/private_key.pem", "KALSHI_ENV": "demo" } } } }

Why not just `.env` in the project dir? MCP clients spawn the

server as a subprocess from their own working directory (typically

your home dir on macOS/Linux, the client's install dir on Windows),

so a .env sitting in this repo wouldn't get found. Hence

--env-file to point at it explicitly. Running the server directly

from the project dir (no client) still works without flags — the

CLI auto-loads ./.env when launched there.

Use as a remote MCP service

For clients that don't speak local stdio — currently the main one being claude.ai's custom connector form, which only supports OAuth-protected HTTP — host the server somewhere reachable and point the client at it. The OAuth proxy is bundled with the server; you just need to configure it.

The proxy lets any GitHub account sign in, so HTTP transport also requires an identity allowlist — MCP_ALLOWED_GITHUB_IDS (numeric ids, preferred: they survive renames) and/or MCP_ALLOWED_GITHUB_LOGINS — enforced on every MCP request (tool calls, resource reads such as kalshi://balance, and listings). HTTP refuses to start on a partial OAuth config, and unauthenticated HTTP (MCP_ALLOW_INSECURE_HTTP=1) is confined to a loopback bind with DNS-rebinding protection unless you also set MCP_ALLOW_INSECURE_PUBLIC_BIND=1.

See DEPLOY.md for an end-to-end walkthrough using Render + GitHub OAuth + Upstash