mcp-kraken

Servidor MCP que encapsula a API REST Spot da exchange de criptomoedas Kraken via HTTP.

Documentação

mcp-kraken

[!WARNING] Software alfa. Interfaces e padrões podem mudar em qualquer versão menor até a v1.0. Nenhuma responsabilidade por perdas financeiras, negociações perdidas ou saques mal roteados. Não é aconselhamento financeiro. Não afiliado à Kraken ou à Payward Inc. Consulte o Aviso legal completo abaixo antes de conceder ao servidor credenciais com permissões de negociação ou saque.

Um servidor MCP que expõe a API REST Spot da exchange de criptomoedas Kraken via HTTP, protegida com tokens de portador que você gerencia localmente.

Superfície completa da API REST Spot da Kraken, mapeada para ferramentas MCP tipadas.
Detecção proativa de permissões de chave de API — chamadas que a chave não pode executar são rejeitadas antes de saírem do servidor, com um erro claro.
CLI de token integrada: gere, liste e revogue tokens de portador usados por clientes HTTP para autenticar contra o próprio MCP.
Sonda de disponibilidade GET /health — sem necessidade de credenciais; segura para healthchecks do Docker, sondas do Kubernetes e pings de balanceadores de carga.
Processo único, sem estado além do armazenamento de tokens SQLite; pronto para implantação conteinerizada atrás de um proxy reverso.

WebSocket v2 e transportes FIX estão explicitamente fora do escopo do primeiro lançamento — consulte TODO.md.

Arquitetura

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

Duas fronteiras de autenticação:

Fronteira	Mecanismo
Cliente MCP → mcp-kraken (você controla)	Tokens de portador opacos (SHA-256)
mcp-kraken → Kraken (você controla)	`KRAKEN_API_KEY` + assinatura HMAC

Requisitos

Python >=3.12
uv para gerenciamento de dependências
just para o executor de comandos de desenvolvimento (opcional)
Uma chave de API Spot da Kraken — gere uma em Conta → Segurança → API. As permissões que você habilitar na chave determinam diretamente quais ferramentas MCP funcionarão (consulte Permissões abaixo).

Início 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

Aponte seu cliente MCP para http://localhost:8765/mcp/ e autentique com o token de portador. Dois métodos são suportados:

Método	Quando usar
Cabeçalho `Authorization: Bearer mck_…`	Preferido — o token fica fora de URLs e logs
Parâmetro de consulta `?apikey=mck_…`	Alternativa para clientes que não podem definir cabeçalhos personalizados (ex.: conector remoto do Claude Desktop)

O servidor remove ?apikey= da URL antes de encaminhar para a camada MCP e o oculta dos logs de acesso (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 aceita --expires-in 90d (ou 12h, 30m, 3600 segundos). Omita para um token que nunca expira. O texto completo é mostrado apenas uma vez na criação — o servidor armazena somente o hash SHA-256 e o ID curto.

Teste local com Claude Desktop

O Claude Desktop aceita servidores MCP como conector HTTPS remoto ou como comando local (stdio). Certificados autoassinados puros são rejeitados — o certificado precisa ser assinado por uma CA confiável pelo sistema operacional.

Opção A — HTTPS via mkcert (Conector personalizado)

mkcert cria uma CA local, instala-a no armazenamento de confiança do sistema e assina certificados a partir dela.

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

Depois, no Claude Desktop: Configurações → Conectores → Adicionar conector personalizado, com URL https://localhost:8765/mcp/ e o token de portador de mcp-kraken token create.

Dica — O Claude Desktop não pode definir cabeçalhos personalizados. Se a interface do conector não tiver um campo "cabeçalho de autorização", acrescente o token como parâmetro de consulta em vez disso: https://localhost:8765/mcp/?apikey=mck_…
O servidor o converte em um cabeçalho Authorization: Bearer adequado internamente e oculta o valor dos logs de acesso.

Opção B — stdio (Conector de comando)

Para uso puramente local, você pode pular o HTTPS completamente:

uv run mcp-kraken serve --stdio

Conecte-o ao arquivo de configuração do 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": "..."
      }
    }
  }
}

Sessões stdio são inerentemente locais — a camada de token de portador é ignorada.

Configuração

As configurações vêm de variáveis de ambiente, opcionalmente carregadas de .env:

Variável	Padrão	Finalidade
`KRAKEN_API_KEY`	—	Chave pública da API Kraken.
`KRAKEN_API_SECRET`	—	Chave privada da API Kraken (base64).
`KRAKEN_BASE_URL`	`https://api.kraken.com`	Substituição para testes.
`MCP_KRAKEN_HOST`	`0.0.0.0`	Endereço de bind.
`MCP_KRAKEN_PORT`	`8765`	Porta TCP.
`MCP_KRAKEN_PATH`	`/mcp`	Caminho HTTP onde o transporte MCP é montado.
`MCP_KRAKEN_TOKEN_DB`	`./data/tokens.db`	Arquivo SQLite que armazena metadados de tokens de portador.
`MCP_KRAKEN_SSL_KEYFILE`	—	Chave privada TLS (PEM). Emparelhe com `_SSL_CERTFILE`.
`MCP_KRAKEN_SSL_CERTFILE`	—	Certificado TLS (PEM). Emparelhe com `_SSL_KEYFILE`.
`MCP_KRAKEN_HTTP_TIMEOUT`	`30`	Segundos antes do timeout de chamadas de saída à Kraken.
`MCP_KRAKEN_LOG_LEVEL`	`INFO`	Nível de log padrão do Python.
`MCP_KRAKEN_AUTH_DISABLED`	`false`	Somente desenvolvimento. Ignora a aplicação de token de portador.

O exemplo completo está em .env.example.

Ferramentas

Ferramentas públicas de dados de mercado (sem necessidade de credenciais 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.

Ferramentas privadas (exigem KRAKEN_API_KEY + KRAKEN_API_SECRET):

Conta: 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.
Negociação: 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.
Financiamento: 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.
Subcontas: create_subaccount, account_transfer.
Autenticação WebSocket: get_websockets_token (token para a futura camada WS — consulte TODO.md).

Permissões de chave de API Kraken

As chaves Kraken podem ser emitidas com qualquer subconjunto de:

Rótulo na interface	Sinalizador de capacidade
Consultar fundos	`query_funds`
Depósito	`deposit`
Saque	`withdraw`
Earn	`earn`
Ver ordens e negociações abertas	`query_open_orders`
Ver ordens e negociações fechadas	`query_closed_orders`
Criar e modificar ordens	`create_modify_orders`
Cancelar e fechar ordens	`cancel_orders`
Ver entradas de razão	`query_ledger`
Exportar dados	`export_data`
Interface WebSocket	`websocket`

Na primeira chamada privada, mcp-kraken inspeciona a chave via GetAPIKeyInfo e armazena em cache o conjunto de permissões resultante. Invocações subsequentes de ferramentas são verificadas contra esse cache; permissões ausentes geram KrakenPermissionError com a lista de sinalizadores que a chave precisaria. Se a introspecção em si falhar (chaves mais antigas podem não suportar GetAPIKeyInfo), o servidor recorre a deixar a Kraken aplicar as permissões pela rede.

Restrições de IP, expiração, intervalos de datas de consulta e janelas de nonce personalizadas são configuradas na própria chave na interface da Kraken; o servidor repassa o que a chave permitir.

Desenvolvimento

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

Execute just sem argumentos para a lista completa de receitas.

Docker

A imagem publicada é ghcr.io/xavierbeheydt/mcp-kraken:

Tag	Enviada por	Notas
`latest`	fluxo de release	Tag mais recente sem pré-lançamento.
`vX.Y.Z`, `vX.Y`, `vX`	fluxo de release	Tags semver em cada release.
`dev`	fluxo de publicação de desenvolvimento	Ponta do branch `dev`.
`dev-<sha7>`	fluxo de publicação de desenvolvimento	Tag por commit em `dev`.

A implantação de referência usa compose.yml:

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

O contêiner executa como usuário não raiz (uid 10001), com sistema de arquivos raiz somente leitura, sem capacidades adicionadas e um volume SQLite de armazenamento de tokens em /data. Coloque-o atrás de um proxy reverso com terminação TLS em produção — o servidor fala HTTP simples internamente.

Endpoint de saúde

GET /health retorna 200 {"status":"ok"} sem token de portador — seguro para orquestradores, balanceadores de carga e monitores de disponibilidade:

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

Tanto o Dockerfile HEALTHCHECK quanto o compose.yml usam este endpoint.

Versionamento e fluxo de release

As versões são derivadas de tags git via hatch-vcs; não há número de versão para alterar em 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

Convenções de branch:

main — protegido; sempre igual ao commit de release mais recente.
dev — branch de integração padrão; cada push executa testes e republica a imagem :dev.
branches de tópico → PR para dev.
Releases são cortados marcando o commit desejado de dev com vX.Y.Z. O fluxo de release o testa, compila e envia a imagem com tags semver, abre um Release do GitHub com notas geradas automaticamente e avança main para a tag. Se main não puder ser avançado (ex.: main divergiu), o fluxo emite um aviso e deixa a mesclagem para um humano.

Para pré-lançamento, marque v1.2.3-rc1: o fluxo compila e envia 1.2.3-rc1, 1.2-rc1, 1-rc1, marca o Release do GitHub como pré-lançamento e não publica a tag :latest.

Aviso legal

[!CAUTION] Leia esta seção antes de apontar mcp-kraken para uma chave de API Kraken com permissões de negociação ou saque. Software em versão alfa. Assinaturas de ferramentas, comportamentos padrão, chaves de configuração e o formato de token em disco podem mudar em qualquer versão menor até a v1.0. Execute uma instância não produtiva com uma chave de API Kraken somente leitura primeiro, e leia a docstring de cada ferramenta antes de conceder ao servidor credenciais com permissões de negociação ou saque.

Sem responsabilidade. O software é fornecido como está, sem garantia de qualquer tipo, expressa ou implícita. O autor não é responsável por qualquer perda financeira direta, indireta, incidental ou consequente decorrente do uso, uso indevido ou indisponibilidade deste software — incluindo, mas não se limitando a saques mal roteados, negociações não intencionais, execuções perdidas, indisponibilidade da exchange, limites de taxa da API ou credenciais comprometidas.

Não é aconselhamento financeiro. Nada neste software, em sua documentação ou em qualquer saída de ferramenta constitui aconselhamento de investimento, negociação, tributário ou jurídico. Você é o único responsável pelas decisões que toma e pelas ordens que envia.

Não afiliado à Kraken ou à Payward Inc. "Kraken" é uma marca registrada de seu respectivo proprietário. Este projeto é um cliente independente da API REST pública da Kraken, escrito com base na superfície de API publicamente documentada.