Kalshi MCP Server

Um servidor MCP simples para interagir com o mercado de previsão Kalshi

GitHubExperimente este MCPPatrocinado

Documentação

kalshi-mcp-server

Um servidor MCP que permite que IA opere no mercado de previsão, Kalshi

Ferramentas Implementadas

get_tags_for_series_categories
- Chama o endpoint público da Kalshi: GET /search/tags_by_categories
- Nenhuma chave de API necessária
get_balance
- Chama o endpoint privado da Kalshi: GET /portfolio/balance
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
get_subaccount_balances
- Chama o endpoint privado da Kalshi: GET /portfolio/subaccounts/balances
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
create_subaccount
- Chama o endpoint privado da Kalshi: POST /portfolio/subaccounts
- Sem argumentos
- Cria uma nova subconta (máximo 32 por usuário)
- Retorna: subaccount_number (int, 1-32)
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
get_orders
- Chama o endpoint privado da Kalshi: GET /portfolio/orders
- Argumentos opcionais:
  - ticker (string; ticker do mercado)
  - event_ticker (string; tickers de eventos separados por vírgula, máximo 10)
  - status (string: resting|canceled|executed)
  - min_ts/max_ts (int; segundos unix)
  - limit (int, 1-200)
  - cursor (string)
  - subaccount (int, 0-32)
- Retorna ordens do portfólio (e cursor de paginação opcional)
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
get_order
- Chama o endpoint privado da Kalshi: GET /portfolio/orders/{order_id}
- Argumentos obrigatórios:
  - order_id (string; o identificador da ordem)
- Retorna um único objeto de ordem com todos os campos da ordem
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
create_order
- Chama o endpoint privado da Kalshi: POST /portfolio/orders
- Argumentos obrigatórios:
  - ticker (string; ticker do mercado)
  - side (string: yes|no)
  - action (string: buy|sell)
- Argumentos opcionais:
  - client_order_id (string; ID de ordem especificado pelo chamador)
  - count (int, >=1; quantidade de contratos)
  - count_fp (string; contagem de contratos em ponto fixo)
  - yes_price (int, 1-99; preço em centavos)
  - no_price (int, 1-99; preço em centavos)
  - yes_price_dollars (string; preço "yes" em dólares)
  - no_price_dollars (string; preço "no" em dólares)
  - expiration_ts (int; timestamp unix para expiração da ordem)
  - time_in_force (string: fill_or_kill|good_till_canceled|immediate_or_cancel)
  - buy_max_cost (int; custo máximo em centavos)
  - sell_position_floor (int; obsoleto, apenas 0 permitido se definido)
  - post_only (boolean)
  - reduce_only (boolean)
  - self_trade_prevention_type (string: taker_at_cross|maker)
  - order_group_id (string)
  - cancel_order_on_pause (boolean)
  - subaccount (int, 0-32)
- Retorna detalhes da ordem criada
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
cancel_order
- Chama o endpoint privado da Kalshi: DELETE /portfolio/orders/{order_id}
- Argumentos obrigatórios:
  - order_id (string; o identificador da ordem)
- Argumentos opcionais:
  - subaccount (int, 0-32)
- Retorna o objeto da ordem cancelada e o número de contratos reduzidos (reduced_by, reduced_by_fp)
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
get_positions
- Chama o endpoint privado da Kalshi: GET /portfolio/positions
- Argumentos opcionais:
  - cursor (string)
  - limit (int, 1-1000; padrão 100)
  - count_filter (string; separado por vírgula de position e/ou total_traded)
  - ticker (string; ticker do mercado)
  - event_ticker (string; tickers de eventos separados por vírgula, máximo 10)
  - subaccount (int, 0-32)
- Retorna posições do portfólio com arrays market_positions e event_positions, além do cursor de paginação
- Requer autenticação por chave de API (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
get_categories
- Chama o endpoint público da Kalshi: GET /search/tags_by_categories
- Retorna apenas os nomes das categorias
- Nenhuma chave de API necessária
get_tags_for_series_category
- Chama o endpoint público da Kalshi: GET /search/tags_by_categories
- Requer um argumento: category (nome exato da categoria)
- Retorna tags para a categoria selecionada
- Nenhuma chave de API necessária
get_series_list
- Chama o endpoint público da Kalshi: GET /series
- Argumentos opcionais:
  - category (string)
  - tags (string)
  - cursor (string)
  - limit (int, 1-1000)
  - include_product_metadata (boolean)
  - include_volume (boolean)
- Retorna objetos de série tipados da resposta da Kalshi
- Registra detalhes de aviso/erro quando campos da resposta têm tipos/formas inesperados
- Nenhuma chave de API necessária
get_series_tickers_for_category
- Pagina o endpoint público da Kalshi: GET /series
- Argumentos obrigatórios:
  - category (string)
- Argumentos opcionais:
  - tags (string)
  - limit (int, 1-1000; padrão 1000)
  - max_pages (int, 1-10000; padrão 1000)
- Retorna apenas valores de ticker em todas as páginas
- Nenhuma chave de API necessária
get_markets
- Chama o endpoint público da Kalshi: GET /markets
- Argumentos opcionais:
  - cursor (string)
  - limit (int, 1-1000)
  - status (string; a documentação da Kalshi lista valores como unopened|open|paused|closed|settled)
  - tickers (string; tickers de mercado separados por vírgula)
  - event_ticker (string; tickers de eventos separados por vírgula)
  - series_ticker (string)
  - mve_filter (string: only|exclude)
  - min_created_ts/max_created_ts (int; segundos unix)
  - min_updated_ts (int; segundos unix)
  - min_close_ts/max_close_ts (int; segundos unix)
  - min_settled_ts/max_settled_ts (int; segundos unix)
- Retorna mercados tipados da resposta da Kalshi
- Nenhuma chave de API necessária
get_open_markets_for_series
- Pagina o endpoint público da Kalshi: GET /markets
- Argumentos obrigatórios:
  - series_ticker (string)
- Argumentos opcionais:
  - limit (int, 1-1000; padrão 1000)
  - max_pages (int, 1-10000; padrão 1000)
- Força status=open e retorna todos os mercados em todas as páginas
- Nenhuma chave de API necessária
get_open_market_titles_for_series
- Pagina o endpoint público da Kalshi: GET /markets
- Argumentos obrigatórios:
  - series_ticker (string)
- Argumentos opcionais:
  - limit (int, 1-1000; padrão 1000)
  - max_pages (int, 1-10000; padrão 1000)
- Força status=open e retorna apenas ticker, title, subtitle, yes_sub_title, no_sub_title para cada mercado em todas as páginas
- Nenhuma chave de API necessária

Configuração

KALSHI_API_BASE_URL
- Padrão: https://api.elections.kalshi.com/trade-api/v2
KALSHI_TIMEOUT_SECONDS
- Padrão: 10
KALSHI_API_KEY_ID
- Necessário para endpoints autenticados/privados (por exemplo, get_balance)
KALSHI_API_KEY_PATH
- Necessário para endpoints autenticados/privados
- Caminho para o arquivo PEM da chave privada da API Kalshi
.env
- load_settings() lê um arquivo local .env da raiz do repositório e carrega variáveis quando elas ainda não estão definidas no ambiente

Executar como servidor MCP stdio

Comando (instalado/editável):
- python3 -m pip install -e .
- python3 -m kalshi_mcp.server
Comando (sem instalação):
- PYTHONPATH=src python3 -m kalshi_mcp.server
Transporte:
- JSON-RPC 2.0 sobre JSON delimitado por nova linha em stdin/stdout

Desenvolvimento

Executar testes unitários (unittest):
- python3 -m unittest discover -s tests -p 'test_*.py'
Executar testes unitários (pytest):
- Instalar dependências de desenvolvimento: python3 -m pip install -r requirements-dev.txt
- Depois: python3 -m pytest -q