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