MCP Server Kalshi

Um servidor Kalshi de leitura/escrita

Documentação

MCP Server Kalshi

Um servidor MCP que oferece a Claude Code e outras ferramentas de agente uma interface de primeira classe para o Kalshi. Ele foi construído para negociação de ponta a ponta: navegue pelos mercados, pesquise-os, leia as regras de liquidação exatas (incluindo o download dos PDFs de termos de contrato) e execute negociações — tudo por meio de ferramentas MCP.

Destaques

Descoberta — list_markets, get_market, list_events, get_event, list_series, get_series. (O Kalshi não tem busca por texto livre; os filtros list_markets são a busca.)
Pesquisa — get_market_orderbook, get_market_candlesticks, get_market_trades.
Regras detalhadas — get_market_rules consolida os rules_primary/rules_secondary de um mercado, condições de fechamento antecipado, fontes de liquidação e proibições de série; fetch_rules_pdf baixa e extrai o texto do PDF do contrato legal real para que o agente possa lê-lo.
Bolsa — get_exchange_status, get_exchange_schedule (se o mercado está aberto e seus horários).
Portfólio — get_balance, get_positions, get_fills, get_settlements.
Negociação — create_order, cancel_order, amend_order, decrease_order, além de list_orders / get_order.

Segurança por padrão

O servidor tem como alvo o ambiente demo (sandbox) do Kalshi, a menos que você defina explicitamente KALSHI_ENV=prod.
As ferramentas de colocação de ordens (create_order, amend_order) exigem confirm=true. Sem ele, elas retornam uma prévia — um resumo legível por humanos e a carga exata — e não colocam nada.
As credenciais são opcionais: todas as ferramentas de mercado/regras funcionam sem autenticação. Apenas as ferramentas de portfólio e ordens precisam de chave de API + chave privada RSA.

Modelo de ordens intuitivo

A API de ordens V2 do Kalshi cotates tudo a partir da perna YES (bid/ask em dólares de ponto fixo). Este servidor expõe o modelo natural em vez disso — action (comprar/vender) + side (sim/não) + um preço limite em centavos inteiros — e o traduz (incluindo a inversão de preço comprar-NO ⇄ vender-YES).

Configuração

Variável	Padrão	Finalidade
`KALSHI_ENV`	`demo`	`demo` (sandbox) ou `prod` (dinheiro real). Deriva a URL base.
`KALSHI_API_KEY`	(nenhum)	ID da chave de API do Kalshi. Exigida apenas para ferramentas autenticadas.
`KALSHI_PRIVATE_KEY_PATH`	(nenhum)	Caminho para sua chave privada RSA `.pem`. Exigida para ferramentas autenticadas.
`BASE_URL`	(derivado)	Substituição explícita opcional da base REST (deve incluir `/trade-api/v2`).

Consulte .env-example. Obtenha credenciais de API em docs.kalshi.com/getting_started/api_keys e uma conta demo por meio do guia do ambiente demo.

Claude Desktop (uvx)

"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)

"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"
    }
  }
}

Desenvolvimento local

Crie um arquivo .env (consulte .env-example).
Instale as dependências: uv sync (adicione --extra dev para ferramentas de desenvolvimento). Requer Python 3.10+.
Execute: uv run start.
Teste: uv run pytest.

MCP Inspector

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-server-kalshi run start

Testes e qualidade de código

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

Os testes são puros/offline — eles exercitam a tradução de ordens e a etapa de confirmação, o cliente HTTP (por meio de um httpx.MockTransport injetado), o registro de ferramentas MCP, a configuração e a extração de PDF, tudo sem tocar na API live do Kalshi. A CI (.github/workflows/ci.yml) executa ruff + black + mypy + pytest nas versões Python 3.10–3.13 a cada push/PR, e os lançamentos são condicionados a essa mesma suíte.

Autenticação

As solicitações são assinadas com RSA-PSS (MGF1-SHA256, salt máximo). Cada solicitação autenticada envia KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP e KALSHI-ACCESS-SIGNATURE, onde a mensagem assinada é timestamp_ms + METHOD + path (o caminho inclui /trade-api/v2, exclui a string de consulta).