mcp-server-kalshi

# MCP Server Kalshi <!-- mcp-name: io.github.9crusher/mcp-server-kalshi --> An MCP server that gives Claude Code and other agent harnesses a first-class interface to [Kalshi](https://kalshi.com). It is built for end-to-end trading: browse markets, research them, read the *exact* settlement rules (including pulling the contract-terms PDFs), and execute trades — all through MCP tools. ## Highlights - **Discovery** — `list_markets`, `get_market`, `list_events`, `get_event`, `list_series`, `get_series`. (Kalshi has no free-text search; `list_markets` filters are the search.) - **Research** — `get_market_orderbook`, `get_market_candlesticks`, `get_market_trades`. - **Deep rules** — `get_market_rules` consolidates a market's `rules_primary`/`rules_secondary`, early-close conditions, settlement sources, and series prohibitions; `fetch_rules_pdf` downloads and extracts the text of the actual legal contract PDF so the agent can read it. - **Exchange** — `get_exchange_status`, `get_exchange_schedule` (is the market open, and its hours). - **Portfolio** — `get_balance`, `get_positions`, `get_fills`, `get_settlements`. - **Trading** — `create_order`, `cancel_order`, `amend_order`, `decrease_order`, plus `list_orders` / `get_order`. ### Safety by default - The server targets Kalshi's **demo (sandbox)** environment unless you explicitly set `KALSHI_ENV=prod`. - Order-placing tools (`create_order`, `amend_order`) require `confirm=true`. Without it they return a **preview** — a human-readable summary and the exact payload — and place nothing. - Credentials are **optional**: all market/rules tools work unauthenticated. Only portfolio and order tools need an API key + RSA private key. ### Intuitive order model Kalshi's V2 order API quotes everything from the YES leg (`bid`/`ask` in fixed-point dollars). This server exposes the natural model instead — `action` (buy/sell) + `side` (yes/no) + a whole **cents** limit price — and translates it (including the buy-NO ⇄ sell-YES price inversion). ## Configuration | Variable | Default | Purpose | |----------|---------|---------| | `KALSHI_ENV` | `demo` | `demo` (sandbox) or `prod` (real money). Derives the base URL. | | `KALSHI_API_KEY` | _(none)_ | Kalshi API key ID. Required only for authenticated tools. | | `KALSHI_PRIVATE_KEY_PATH` | _(none)_ | Path to your RSA private key `.pem`. Required for authenticated tools. | | `BASE_URL` | _(derived)_ | Optional explicit REST base override (must include `/trade-api/v2`). | See `.env-example`. Get API credentials at [docs.kalshi.com/getting_started/api_keys](https://docs.kalshi.com/getting_started/api_keys) and a demo account via the [demo environment guide](https://docs.kalshi.com/getting_started/test_in_demo). ### Claude Desktop (uvx) ```json "mcpServers": { "kalshi": { "command": "uvx", "args": ["mcp-server-kalshi"], "env": { "KALSHI_ENV": "demo", "KALSHI_API_KEY": "<YOUR KALSHI API KEY>", "KALSHI_PRIVATE_KEY_PATH": "PATH TO YOUR RSA KEY FILE" } } } ``` ### Claude Desktop (Docker) ```json "mcpServers": { "kalshi": { "command": "docker", "args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "-e", "KALSHI_ENV", "-e", "KALSHI_API_KEY", "-e", "KALSHI_PRIVATE_KEY_PATH", "mcp-server-kalshi"], "env": { "KALSHI_ENV": "demo", "KALSHI_API_KEY": "<YOUR KALSHI API KEY>", "KALSHI_PRIVATE_KEY_PATH": "PATH TO YOUR RSA KEY FILE" } } } ``` ## Local Development 1. Create a `.env` file (see `.env-example`). 2. Install deps: `uv sync` (add `--extra dev` for dev tools). Requires Python 3.10+. 3. Run: `uv run start`. 4. Test: `uv run pytest`. ### MCP Inspector ```bash npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-server-kalshi run start ``` ## Testing & code quality ```bash uv sync --extra dev # install dev tools (ruff, mypy, pytest, ...) uv run pytest # run the test suite uv run pytest --cov # tests with a coverage report uv run ruff check src tests # lint uv run black src tests # format (add --check to verify only) uv run mypy # type check uv run pre-commit install # (once) run ruff + black on every commit ``` Tests are pure/offline — they exercise the order translation and confirm-gate, the HTTP client (via an injected `httpx.MockTransport`), the MCP tool registry, config, and PDF extraction, all without touching the live Kalshi API. CI (`.github/workflows/ci.yml`) runs ruff + black + mypy + pytest across Python 3.10–3.13 on every push/PR, and releases are gated on that same suite. ## Authentication Requests are signed with RSA-PSS (MGF1-SHA256, max salt). Each authenticated request sends `KALSHI-ACCESS-KEY`, `KALSHI-ACCESS-TIMESTAMP`, and `KALSHI-ACCESS-SIGNATURE`, where the signed message is `timestamp_ms + METHOD + path` (path includes `/trade-api/v2`, excludes the query string).