MCP Server Kalshi

Un servidor Kalshi de lectura/escritura

Documentación

MCP Server Kalshi

Un servidor MCP que brinda a Claude Code y otros entornos de agentes una interfaz de primera clase para Kalshi. Está diseñado para trading de extremo a extremo: explora mercados, investígalos, lee las reglas de liquidación exactas (incluyendo la descarga de los PDFs de términos del contrato) y ejecuta operaciones, todo a través de herramientas MCP.

Destacados

Descubrimiento — list_markets, get_market, list_events, get_event, list_series, get_series. (Kalshi no tiene búsqueda de texto libre; los filtros de list_markets son la búsqueda).
Investigación — get_market_orderbook, get_market_candlesticks, get_market_trades.
Reglas profundas — get_market_rules consolida las rules_primary/rules_secondary de un mercado, condiciones de cierre anticipado, fuentes de liquidación y prohibiciones de series; fetch_rules_pdf descarga y extrae el texto del PDF del contrato legal real para que el agente pueda leerlo.
Exchange — get_exchange_status, get_exchange_schedule (si el mercado está abierto y sus horarios).
Portafolio — get_balance, get_positions, get_fills, get_settlements.
Trading — create_order, cancel_order, amend_order, decrease_order, además de list_orders / get_order.

Seguridad por defecto

El servidor apunta al entorno demo (sandbox) de Kalshi a menos que establezcas explícitamente KALSHI_ENV=prod.
Las herramientas de colocación de órdenes (create_order, amend_order) requieren confirm=true. Sin él, devuelven una vista previa — un resumen legible por humanos y el payload exacto — y no colocan nada.
Las credenciales son opcionales: todas las herramientas de mercados/reglas funcionan sin autenticación. Solo las herramientas de portafolio y órdenes necesitan una clave API + clave privada RSA.

Modelo de órdenes intuitivo

La API de órdenes V2 de Kalshi cotiza todo desde la pata YES (bid/ask en dólares de punto fijo). Este servidor expone el modelo natural en su lugar — action (comprar/vender) + side (sí/no) + un precio límite en centavos enteros — y lo traduce (incluyendo la inversión de precio comprar-NO ⇄ vender-YES).

Configuración

Variable	Predeterminado	Propósito
`KALSHI_ENV`	`demo`	`demo` (sandbox) o `prod` (dinero real). Deriva la URL base.
`KALSHI_API_KEY`	(ninguno)	ID de clave API de Kalshi. Requerido solo para herramientas autenticadas.
`KALSHI_PRIVATE_KEY_PATH`	(ninguno)	Ruta a tu clave privada RSA `.pem`. Requerida para herramientas autenticadas.
`BASE_URL`	(derivado)	Anulación opcional explícita de la base REST (debe incluir `/trade-api/v2`).

Consulta .env-example. Obtén credenciales API en docs.kalshi.com/getting_started/api_keys y una cuenta demo a través de la guía del entorno 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"
    }
  }
}

Desarrollo local

Crea un archivo .env (consulta .env-example).
Instala dependencias: uv sync (agrega --extra dev para herramientas de desarrollo). Requiere Python 3.10+.
Ejecuta: uv run start.
Prueba: uv run pytest.

MCP Inspector

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

Pruebas y calidad 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

Las pruebas son puras/sin conexión — ejercitan la traducción de órdenes y la puerta de confirmación, el cliente HTTP (vía un httpx.MockTransport inyectado), el registro de herramientas MCP, la configuración y la extracción de PDF, todo sin tocar la API en vivo de Kalshi. CI (.github/workflows/ci.yml) ejecuta ruff + black + mypy + pytest en Python 3.10–3.13 en cada push/PR, y los lanzamientos están sujetos a esa misma suite.

Autenticación

Las solicitudes se firman con RSA-PSS (MGF1-SHA256, sal máxima). Cada solicitud autenticada envía KALSHI-ACCESS-KEY, KALSHI-ACCESS-TIMESTAMP y KALSHI-ACCESS-SIGNATURE, donde el mensaje firmado es timestamp_ms + METHOD + path (la ruta incluye /trade-api/v2, excluye la cadena de consulta).