io.github.9crusher/mcp-server-kalshi
MCP server for end-to-end trading on Kalshi prediction markets: discover, research, trade.
Open source Open in the app JSON README (API)
About
MCP server for end-to-end trading on Kalshi prediction markets: discover, research, trade.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- 9crusher
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.2
- Stars
- 27
- Forks
- 11
- Open pull requests
- 1
- Last push
- 2026-08-23T13:08:36Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:01:38
- Updated
- 2026-08-29 03:01:38
- Origin id
io.github.9crusher/mcp-server-kalshi
README
# 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).