Content
# Kalshi MCP Server
FastMCP server for Kalshi's Trade API.
## Setup
This repo vendors `fastmcp/`, so run commands from the repository root:
```bash
python -m kalshi_mcp.server
```
By default the server uses Kalshi's demo API host. Configure it with environment variables:
```bash
export KALSHI_ENV=demo
export KALSHI_API_KEY_ID="your-key-id"
export KALSHI_PRIVATE_KEY_PATH="/path/to/kalshi-private-key.pem"
```
You can also provide `KALSHI_PRIVATE_KEY` directly. Escaped newlines are supported.
Trading tools are disabled unless explicitly enabled:
```bash
export KALSHI_ENABLE_TRADING=true
```
Even then, `order_create`, `order_cancel`, `rfq_create`, and `rfq_delete` require `confirm=true` on each call.
## Tool Coverage
The server exposes 49 tools covering the core Predictions REST API areas:
- Exchange status, schedule, announcements, and user-data timestamp
- Markets, market orderbooks, market trades, candlesticks, and series
- Events, event metadata, event fee changes, event candlesticks, and multivariate events
- Portfolio balance, subaccount balances, positions, fills, settlements, deposits, and withdrawals
- Orders, order lookup, order queue positions, V2 create order, and V2 cancel order
- Account limits, API usage progress, endpoint costs, and API key listing
- Historical cutoffs, historical markets, historical candlesticks, historical trades, historical orders, and historical fills
- Communications ID, RFQs, quotes, create RFQ, and delete RFQ
Tool names are prefix-grouped for IDEs and MCP clients that display tools as a flat list:
- `exchange_*`
- `market_*`
- `series_*`
- `event_*`
- `portfolio_*`
- `order_*`
- `account_*`
- `historical_*`
- `communications_*`, `rfq_*`, and `quote_*`
## Local MCP Config
Many IDEs and MCP clients can run this server from an `mcp.json` config. Use this shape and adjust paths/secrets for your machine:
```json
{
"mcpServers": {
"kalshi": {
"command": "python",
"args": ["-m", "kalshi_mcp.server"],
"cwd": "",
"env": {
"KALSHI_API_KEY_ID": "your-key-id",
"KALSHI_PRIVATE_KEY_PATH": "/path/to/kalshi-private-key.pem"
}
}
}
}
```
For public market-data tools, the `env` block can be omitted. Authenticated portfolio/order tools require `KALSHI_API_KEY_ID` and either `KALSHI_PRIVATE_KEY_PATH` or `KALSHI_PRIVATE_KEY`.
`cwd` is included because this is a source checkout that vendors `fastmcp/` locally. If you install this package into the Python environment used by your MCP client, `cwd` is not needed.
Optional environment variables:
- `KALSHI_ENV=production` switches from demo to production. The default is `demo`.
- `KALSHI_ENABLE_TRADING=true` enables write tools such as order placement and RFQ creation. Those tools still require `confirm=true` on each call.
## Notes
Kalshi authenticated requests are signed with RSA-PSS over the concatenated timestamp, HTTP method, and request path without query parameters.
