mcp-kraken

Servidor MCP que envuelve la API REST Spot del exchange de criptomonedas Kraken a través de HTTP.

Documentación

mcp-kraken

[!WARNING] Software alfa. Las interfaces y los valores predeterminados pueden cambiar en cualquier versión menor hasta la v1.0. Sin responsabilidad por pérdidas financieras, operaciones no ejecutadas o retiros mal enrutados. No es asesoramiento financiero. No está afiliado a Kraken ni a Payward Inc. Consulte el Aviso legal completo a continuación antes de otorgar al servidor credenciales con permisos de trading o retiro.

Un servidor MCP que expone la API REST Spot de la bolsa de criptomonedas Kraken a través de HTTP, protegida con tokens portadores que usted gestiona localmente.

Superficie completa de la API REST Spot de Kraken, mapeada a herramientas MCP tipadas.
Detección proactiva de permisos de claves API: las llamadas que la clave no puede realizar se rechazan antes de salir del sistema, con un error claro.
CLI de tokens integrada: genere, liste y revoque tokens portadores utilizados por clientes HTTP para autenticarse contra el propio MCP.
Sonda de actividad GET /health — no requiere credenciales; segura para healthchecks de Docker, sondas de Kubernetes y pings de balanceadores de carga.
Proceso único, sin estado más allá del almacén de tokens SQLite; listo para despliegue en contenedores detrás de un proxy inverso.

Los transportes WebSocket v2 y FIX están explícitamente fuera del alcance para la primera versión — consulte TODO.md.

Arquitectura

┌────────────┐    HTTPS / bearer    ┌───────────────┐    HMAC-signed    ┌─────────┐
│ MCP client │ ───────────────────▶ │  mcp-kraken   │ ─────────────────▶│ Kraken  │
│ (Claude…)  │ ◀─────────────────── │  FastMCP HTTP │ ◀───────────────  │ REST v0 │
└────────────┘                      └───────────────┘                   └─────────┘
                                          │
                                          ▼
                                   SQLite (bearer-token hashes)

Dos límites de autenticación:

Límite	Mecanismo
Cliente MCP → mcp-kraken (usted controla)	Tokens portadores opacos (SHA-256)
mcp-kraken → Kraken (usted controla)	`KRAKEN_API_KEY` + firma HMAC

Requisitos

Python >=3.12
uv para la gestión de dependencias
just para el ejecutor de comandos de desarrollo (opcional)
Una clave API Spot de Kraken — genérela en Cuenta → Seguridad → API. Los permisos que habilite en la clave determinan directamente qué herramientas MCP funcionan (consulte Permisos a continuación).

Inicio rápido

# Clone and install
git clone https://github.com/XavierBeheydt/mcp-kraken.git
cd mcp-kraken
uv sync --dev

# Configure
cp .env.example .env
$EDITOR .env  # set KRAKEN_API_KEY and KRAKEN_API_SECRET

# Issue a bearer token for your MCP client
uv run mcp-kraken token create "claude-desktop" --expires-in 90d
# → copy the printed token; it will never be shown again

# Start the HTTP server (defaults to 0.0.0.0:8765/mcp)
uv run mcp-kraken serve

Apunte su cliente MCP a http://localhost:8765/mcp/ y autentíquese con el token portador. Se admiten dos métodos:

Método	Cuándo usarlo
Cabecera `Authorization: Bearer mck_…`	Preferido — el token no aparece en URLs ni registros
Parámetro de consulta `?apikey=mck_…`	Alternativa para clientes que no pueden establecer cabeceras personalizadas (p. ej. conector remoto de Claude Desktop)

El servidor elimina ?apikey= de la URL antes de reenviarla a la capa MCP, y lo redacta de los registros de acceso (apikey=***).

CLI

mcp-kraken serve              # run the HTTP server
mcp-kraken token create NAME  # mint a new bearer token (printed once)
mcp-kraken token list         # list known tokens (hashes only)
mcp-kraken token revoke ID    # revoke a token by id
mcp-kraken version            # print the installed version

token create acepta --expires-in 90d (o 12h, 30m, 3600 segundos). Omita este valor para un token que nunca expire. El texto completo solo se muestra una vez en la creación — el servidor solo almacena el hash SHA-256 más el id corto.

Pruebas locales con Claude Desktop

Claude Desktop acepta servidores MCP como conector HTTPS remoto o como comando local (stdio). Los certificados autofirmados puros se rechazan — el certificado debe estar firmado por una CA que el sistema operativo confíe.

Opción A — HTTPS mediante mkcert (Conector personalizado)

mkcert crea una CA local, la instala en el almacén de confianza del sistema y firma certificados a partir de ella.

brew install mkcert            # or your package manager's equivalent
just cert-local                # mkcert -install + generates certs/{key,cert}.pem
just serve-https               # serves HTTPS on 0.0.0.0:8765/mcp

Luego, en Claude Desktop: Configuración → Conectores → Añadir conector personalizado, con URL https://localhost:8765/mcp/ y el token portador de mcp-kraken token create.

Consejo — Claude Desktop no puede establecer cabeceras personalizadas. Si la interfaz del conector no tiene un campo "Cabecera de autorización", añada el token como parámetro de consulta en su lugar: https://localhost:8765/mcp/?apikey=mck_…
El servidor lo convierte internamente en una cabecera Authorization: Bearer adecuada y redacta el valor de sus registros de acceso.

Opción B — stdio (Conector de comando)

Para uso puramente local puede omitir HTTPS por completo:

uv run mcp-kraken serve --stdio

Conéctelo al archivo de configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kraken": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/mcp-kraken", "run", "mcp-kraken", "serve", "--stdio"],
      "env": {
        "KRAKEN_API_KEY": "...",
        "KRAKEN_API_SECRET": "..."
      }
    }
  }
}

Las sesiones stdio son inherentemente locales — la capa de tokens portadores se omite.

Configuración

Los ajustes provienen de variables de entorno, opcionalmente cargadas desde .env:

Variable	Valor predeterminado	Propósito
`KRAKEN_API_KEY`	—	Clave pública de la API de Kraken.
`KRAKEN_API_SECRET`	—	Clave privada de la API de Kraken (base64).
`KRAKEN_BASE_URL`	`https://api.kraken.com`	Anulación para pruebas.
`MCP_KRAKEN_HOST`	`0.0.0.0`	Dirección de enlace.
`MCP_KRAKEN_PORT`	`8765`	Puerto TCP.
`MCP_KRAKEN_PATH`	`/mcp`	Ruta HTTP donde se monta el transporte MCP.
`MCP_KRAKEN_TOKEN_DB`	`./data/tokens.db`	Archivo SQLite que contiene los metadatos de tokens portadores.
`MCP_KRAKEN_SSL_KEYFILE`	—	Clave privada TLS (PEM). Emparejar con `_SSL_CERTFILE`.
`MCP_KRAKEN_SSL_CERTFILE`	—	Certificado TLS (PEM). Emparejar con `_SSL_KEYFILE`.
`MCP_KRAKEN_HTTP_TIMEOUT`	`30`	Segundos antes de que las llamadas salientes a Kraken expiren.
`MCP_KRAKEN_LOG_LEVEL`	`INFO`	Nivel de registro estándar de Python.
`MCP_KRAKEN_AUTH_DISABLED`	`false`	Solo desarrollo. Omitir la aplicación de tokens portadores.

El ejemplo completo se encuentra en .env.example.

Herramientas

Herramientas públicas de datos de mercado (no se necesitan credenciales de Kraken):

get_server_time, get_system_status, get_assets, get_asset_pairs, get_ticker, get_ohlc, get_order_book, get_recent_trades, get_recent_spreads.

Herramientas privadas (requieren KRAKEN_API_KEY + KRAKEN_API_SECRET):

Cuenta: get_account_balance, get_extended_balance, get_trade_balance, get_trade_volume, get_ledgers, query_ledgers, get_credit_lines, get_api_key_info, request_export_report, get_export_status, retrieve_export, remove_export.
Trading: get_open_orders, get_closed_orders, query_orders, get_trade_history, query_trades, get_open_positions, add_order, add_order_batch, amend_order, edit_order, cancel_order, cancel_all_orders, cancel_all_orders_after, cancel_order_batch.
Financiación: get_deposit_methods, get_deposit_addresses, get_deposit_status, get_withdrawal_methods, get_withdrawal_addresses, get_withdrawal_info, withdraw, get_withdrawal_status, cancel_withdrawal, wallet_transfer.
Earn: list_earn_strategies, list_earn_allocations, allocate_earn, deallocate_earn, get_earn_allocation_status, get_earn_deallocation_status.
Subcuentas: create_subaccount, account_transfer.
Autenticación WebSocket: get_websockets_token (token para la futura capa WS — consulte TODO.md).

Permisos de claves API de Kraken

Las claves de Kraken pueden emitirse con cualquier subconjunto de:

Etiqueta de interfaz	Indicador de capacidad
Consultar fondos	`query_funds`
Depósito	`deposit`
Retiro	`withdraw`
Earn	`earn`
Ver órdenes y operaciones abiertas	`query_open_orders`
Ver órdenes y operaciones cerradas	`query_closed_orders`
Crear y modificar órdenes	`create_modify_orders`
Cancelar y cerrar órdenes	`cancel_orders`
Ver entradas de libro mayor	`query_ledger`
Exportar datos	`export_data`
Interfaz WebSocket	`websocket`

En la primera llamada privada, mcp-kraken inspecciona la clave mediante GetAPIKeyInfo y almacena en caché el conjunto de permisos resultante. Las invocaciones posteriores de herramientas se verifican contra esa caché; los permisos faltantes generan KrakenPermissionError con la lista de indicadores que la clave necesitaría. Si la introspección en sí falla (las claves más antiguas pueden no admitir GetAPIKeyInfo), el servidor recurre a dejar que Kraken aplique los permisos a través de la conexión.

Las restricciones de IP, caducidad, rangos de fechas de consulta y ventanas de nonce personalizadas se configuran en la propia clave en la interfaz de Kraken; el servidor transmite lo que la clave permita.

Desarrollo

just sync          # uv sync --all-extras --dev
just test          # pytest
just check         # lint + format-check + mypy + tests
just fix           # auto-fix lint and format
just docker-build  # local image build

Ejecute just sin argumentos para la lista completa de recetas.

Docker

La imagen publicada es ghcr.io/xavierbeheydt/mcp-kraken:

Etiqueta	Publicada por	Notas
`latest`	flujo de trabajo de lanzamiento	Última etiqueta no preliminar.
`vX.Y.Z`, `vX.Y`, `vX`	flujo de trabajo de lanzamiento	Etiquetas semver en cada lanzamiento.
`dev`	flujo de trabajo de publicación de desarrollo	Punta de la rama `dev`.
`dev-<sha7>`	flujo de trabajo de publicación de desarrollo	Etiqueta por confirmación en `dev`.

El despliegue de referencia utiliza compose.yml:

cp .env.example .env  # set KRAKEN_API_KEY / KRAKEN_API_SECRET
docker compose up -d

El contenedor se ejecuta como un usuario no root (uid 10001), con un sistema de archivos raíz de solo lectura, sin capacidades añadidas y un volumen de almacén de tokens SQLite en /data. Colóquelo detrás de un proxy inverso con terminación TLS en producción — el servidor habla HTTP plano internamente.

Punto final de salud

GET /health devuelve 200 {"status":"ok"} sin token portador — seguro para orquestadores, balanceadores de carga y monitores de disponibilidad:

curl http://localhost:8765/health
# {"status":"ok"}

Tanto el Dockerfile HEALTHCHECK como compose.yml utilizan este punto final.

Versionado y flujo de lanzamiento

Las versiones se derivan de etiquetas git mediante hatch-vcs; no hay número de versión que incrementar en pyproject.toml.

        feature → PR → dev   →  dev-publish workflow → ghcr.io/…:dev[-sha]
                                                      ↑
                                                test workflow

                  tag v1.2.3  →  release workflow    → ghcr.io/…:1.2.3, :latest
                                                      + GitHub Release
                                                      + fast-forward main to the tag

Convenciones de ramas:

main — protegida; siempre equivale a la última confirmación lanzada.
dev — rama de integración predeterminada; cada push ejecuta pruebas y republica la imagen :dev.
ramas de tema → PR hacia dev.
Los lanzamientos se cortan etiquetando la confirmación deseada de dev como vX.Y.Z. El flujo de trabajo de lanzamiento la prueba, compila y publica la imagen con etiquetas semver, abre un lanzamiento de GitHub con notas autogeneradas y avanza rápidamente main hasta la etiqueta. Si main no puede avanzarse rápidamente (p. ej. main ha divergido), el flujo de trabajo emite una advertencia y deja la fusión para un humano.

Para un lanzamiento preliminar, etiquete v1.2.3-rc1: el flujo de trabajo compila y publica 1.2.3-rc1, 1.2-rc1, 1-rc1, marca el lanzamiento de GitHub como preliminar y no publica la etiqueta :latest.

Aviso legal

[!CAUTION] Lea esta sección antes de apuntar mcp-kraken a una clave API de Kraken con permisos de trading o retiro. Software alfa. Las firmas de herramientas, los comportamientos predeterminados, las claves de configuración y el formato de token en disco pueden cambiar en cualquier versión menor hasta la v1.0. Ejecute primero una instancia no productiva con una clave de API de Kraken de solo lectura, y lea la cadena de documentación de cada herramienta antes de otorgar al servidor credenciales con permisos de negociación o retiro.

Sin responsabilidad. El software se proporciona tal cual, sin garantía de ningún tipo, expresa o implícita. El autor no es responsable de ninguna pérdida financiera directa, indirecta, incidental o consecuente derivada del uso, mal uso o indisponibilidad de este software, incluidos, entre otros, retiros mal enrutados, operaciones no intencionadas, ejecuciones omitidas, interrupciones del exchange, límites de tasa de la API o credenciales comprometidas.

No es asesoramiento financiero. Nada en este software, su documentación ni ninguna salida de herramienta constituye asesoramiento de inversión, negociación, fiscal o legal. Usted es el único responsable de las decisiones que tome y de las órdenes que envíe.

No afiliado con Kraken ni Payward Inc. "Kraken" es una marca comercial de su respectivo propietario. Este proyecto es un cliente independiente de la API REST pública de Kraken, escrito según la superficie de API documentada públicamente.