mcp-mercado-bitcoin

Servidor MCP para o Mercado Bitcoin — consulte, compre, venda e gerencie seus ativos digitais diretamente pela sua LLM ou agente de IA favorito.

O que é este MCP?

O Model Context Protocol (MCP) é um protocolo aberto criado pela Anthropic que permite que aplicações de Inteligência Artificial (como Claude, ChatGPT, Cursor e outros) se conectem a ferramentas e fontes de dados externas.

Este servidor MCP expõe a API v4 completa do Mercado Bitcoin como um conjunto de 31 ferramentas que qualquer LLM ou agente de IA compatível pode utilizar. Na prática, isso significa que você pode pedir ao seu assistente de IA para:

• Consultar preços e cotações em tempo real
• Verificar seus saldos e posições
• Comprar e vender criptoativos
• Gerenciar sua carteira, depósitos e saques

Tudo isso via conversa natural, sem precisar navegar pela interface da exchange.

Aviso Legal e Termos de Uso

Riscos de Ativos Digitais

Ativos digitais, incluindo Bitcoin, Ether, tokens de Renda Fixa Digital, Fan Tokens, Utility Tokens, DeFi e outros produtos listados no Mercado Bitcoin, são investimentos de alto risco. O mercado de criptoativos é extremamente volátil e está sujeito a:

• Perda total do capital investido
• Oscilações bruscas e imprevisíveis de preço
• Riscos regulatórios e de liquidez
• Riscos tecnológicos (falhas em smart contracts, ataques a redes, etc.)
• Indisponibilidade temporária ou permanente de plataformas

Criptoativos NÃO são indicados para investidores com perfil Conservador.

Antes de tomar qualquer decisão de investimento, o usuário deve:

1. Conhecer seu perfil de investidor — Preencha sua Análise de Perfil de Investidor (API/Suitability) na sua corretora ou banco
2. Pesquisar e se educar — Consulte fontes confiáveis como:
   • ANBIMA EDU — Educação financeira
   • Banco Central do Brasil — Regulação e informações sobre ativos virtuais
   • CVM - Comissão de Valores Mobiliários — Alertas ao investidor e regulação
3. Buscar orientação profissional — Em caso de dúvidas, consulte um assessor de investimentos ou consultor financeiro certificado antes de operar

Termos de Uso do MCP

ESTE SOFTWARE É FORNECIDO "COMO ESTÁ" (AS IS), SEM GARANTIAS DE QUALQUER NATUREZA.

• Este MCP é uma ferramenta em versão beta e pode conter erros estruturais, bugs, falhas de comunicação com a API do Mercado Bitcoin e outros problemas técnicos
• Os desenvolvedores NÃO se responsabilizam por:
  • Falhas de execução de ordens
  • Indisponibilidades do serviço (do MCP ou do Mercado Bitcoin)
  • Perdas financeiras decorrentes de erros de cotação, latência ou qualquer outro fator
  • Danos diretos, indiretos, incidentais ou consequenciais do uso deste software
• O MCP, no todo ou em parte, poderá ser descontinuado ou retirado do ar sem aviso prévio
• Qualquer cópia, fork ou derivação deste software opera sob seus próprios riscos — os desenvolvedores do projeto original não se responsabilizam por versões de terceiros
• Ao utilizar este MCP, você reconhece e aceita integralmente todos os riscos acima

DYOR — Faça Sua Própria Diligência

Faça sua própria diligência. Pesquise sobre:

• Os ativos digitais que pretende negociar
• O Mercado Bitcoin como plataforma de negociação
• Este MCP como ferramenta de integração

Busque identificar a seriedade, confiabilidade e adequação de cada produto e ferramenta ao seu perfil. Não opere sem compreender plenamente o que está fazendo. Se tiver dúvidas, não opere sem auxílio de profissionais qualificados.

Funcionalidades

• 31 ferramentas cobrindo toda a API v4 do Mercado Bitcoin
• Dados públicos: cotações, livro de ofertas, trades, candles, símbolos, taxas, redes
• Gestão de conta: saldos, posições, nível de tier, taxas de negociação
• Negociação: compra/venda com ordens market, limit, stoplimit e post-only
• Carteira: depósitos, saques, endereços, contas bancárias, sub-contas
• Modelo de segurança em 3 camadas para proteger contra operações não autorizadas
• Compatível com Claude Desktop, Claude Code, OpenClaw, Cursor e qualquer cliente MCP

Modelo de Segurança

Camada 1 — Modos de Operação

Controla quais capacidades ficam disponíveis para a IA:

| Modo | Dados Públicos | Consultas de Conta | Negociação | Saques | | ---- | :------------: | :----------------: | :--------: | :----: | | readonly | Sim | Sim | Não | Não | | trading (padrão) | Sim | Sim | Sim | Não | | full | Sim | Sim | Sim | Sim |

Recomendação: Use readonly para monitoramento, trading para operações de compra/venda (sem saques), e full apenas se você realmente precisa de saques via IA.

Camada 2 — Confirmação em Dois Passos

Toda operação que envolve movimentação financeira (compra, venda, cancelamento, saque, transferência) usa um fluxo obrigatório de confirmação:

1. Primeira chamada (confirm=false) → a IA recebe uma prévia detalhada da operação
2. A IA mostra a prévia ao usuário e pede aprovação explícita
3. Segunda chamada (confirm=true) → a operação é executada somente após aprovação

Defina MB_AUTO_CONFIRM=true apenas se você confia plenamente que o agente opere de forma autônoma. Não recomendado para uso geral.

Camada 3 — Limites de Gasto

| Variável | Descrição | | -------- | --------- | | MB_MAX_ORDER_BRL | Valor máximo por ordem individual (em BRL) | | MB_DAILY_LIMIT_BRL | Volume máximo diário de negociação (em BRL) | | MB_DRY_RUN=true | Modo simulação — nenhuma operação é executada de verdade |

Exemplo: Configure MB_MAX_ORDER_BRL=500 e MB_DAILY_LIMIT_BRL=2000 para limitar a exposição a R$ 500 por ordem e R$ 2.000 por dia.

Autenticação

O MCP utiliza o fluxo OAuth2 Client Credentials do Mercado Bitcoin:

Como obter suas credenciais

1. Faça login na sua conta do Mercado Bitcoin via Web
2. Clique no seu Perfil (canto superior direito)
3. Acesse Configurações
4. No menu lateral esquerdo, localize a seção Integração e clique em Chaves API
5. Clique em Nova Chave
6. Dê um nome para a chave (ex: "MCP Claude", "Agente Trading", etc.)
7. Defina a permissão:
   • Leitura — para monitoramento e consultas apenas
   • Acesso total (permite trades) — para compra, venda e operações
8. Clique em Continuar e siga as instruções de confirmação (2FA)
9. Salve o client_id (Chave de API) e o client_secret (Segredo da API) em local seguro

Configurando a chave no seu Agente de IA

Cada agente ou cliente de IA tem uma forma diferente de receber e armazenar chaves de API. Converse com o agente que você utiliza e garanta que suas credenciais estão registradas de forma segura (variáveis de ambiente, cofre de segredos, etc.).

Os desenvolvedores deste MCP não se responsabilizam pela etapa de configuração de credenciais no seu agente de IA. A segurança das suas chaves é de sua inteira responsabilidade.

Como funciona internamente

• O MCP usa suas credenciais para obter um token Bearer (válido por ~1 hora)
• O token é renovado automaticamente antes de expirar
• Suas credenciais nunca são expostas nas chamadas de ferramentas — apenas o token temporário é utilizado
• Todas as credenciais são passadas via variáveis de ambiente (nunca em código)

Variáveis de Ambiente

| Variável | Obrigatória | Padrão | Descrição | | -------- | :---------: | :----: | --------- | | MB_API_KEY | Para operações autenticadas | — | Client ID (Chave de API) do Mercado Bitcoin | | MB_API_SECRET | Para operações autenticadas | — | Client Secret (Segredo da API) do Mercado Bitcoin | | MB_OPERATION_MODE | Não | trading | Modo de operação: readonly, trading ou full | | MB_AUTO_CONFIRM | Não | false | Pular confirmação em operações perigosas | | MB_MAX_ORDER_BRL | Não | sem limite | Valor máximo por ordem (em BRL) | | MB_DAILY_LIMIT_BRL | Não | sem limite | Limite diário de negociação (em BRL) | | MB_DRY_RUN | Não | false | Modo simulação (não executa operações reais) |

Instalação

npm install -g mcp-mercado-bitcoin

Ou execute diretamente sem instalar:

npx mcp-mercado-bitcoin

Configuração por Cliente

Claude Desktop App (Claude Cowork / Chat)

O Claude Desktop utiliza um arquivo de configuração JSON. Localize-o em:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione o bloco abaixo dentro do arquivo:

{
  "mcpServers": {
    "mercado-bitcoin": {
      "command": "npx",
      "args": ["mcp-mercado-bitcoin"],
      "env": {
        "MB_API_KEY": "seu_client_id_aqui",
        "MB_API_SECRET": "seu_client_secret_aqui",
        "MB_OPERATION_MODE": "trading",
        "MB_MAX_ORDER_BRL": "1000",
        "MB_DAILY_LIMIT_BRL": "5000",
        "MB_DRY_RUN": "false"
      }
    }
  }
}

Após salvar, reinicie completamente o Claude Desktop (feche e abra novamente).

Claude Code (Terminal)

No terminal, execute:

claude mcp add \
  --transport stdio \
  -e MB_API_KEY=seu_client_id_aqui \
  -e MB_API_SECRET=seu_client_secret_aqui \
  -e MB_OPERATION_MODE=trading \
  -e MB_MAX_ORDER_BRL=1000 \
  -e MB_DAILY_LIMIT_BRL=5000 \
  mcp-mercado-bitcoin -- npx mcp-mercado-bitcoin

Para verificar se o servidor está conectado:

claude mcp list

Dentro de uma sessão do Claude Code, use /mcp para verificar o status.

OpenClaw

No arquivo de configuração do OpenClaw (openclaw.config.json ou equivalente), adicione:

{
  "mcpServers": {
    "mercado-bitcoin": {
      "transport": "stdio",
      "command": "npx",
      "args": ["mcp-mercado-bitcoin"],
      "env": {
        "MB_API_KEY": "seu_client_id_aqui",
        "MB_API_SECRET": "seu_client_secret_aqui",
        "MB_OPERATION_MODE": "trading",
        "MB_MAX_ORDER_BRL": "1000",
        "MB_DAILY_LIMIT_BRL": "5000"
      }
    }
  }
}

Outros clientes MCP (Cursor, VS Code, etc.)

Use o transporte stdio com o comando npx mcp-mercado-bitcoin e passe as credenciais via variáveis de ambiente. Consulte a documentação do seu cliente MCP para o formato exato de configuração.

Ferramentas Disponíveis

Status e Utilidade

| Ferramenta | Descrição | | ---------- | --------- | | mb_status | Exibe a configuração atual do servidor: modo de operação, status de autenticação, limites de gasto configurados e valor já negociado no dia |

Dados Públicos (sem autenticação)

Estas ferramentas acessam dados abertos do Mercado Bitcoin. Não requerem chave de API.

| Ferramenta | Descrição | | ---------- | --------- | | mb_get_orderbook | Livro de ofertas (ordens de compra e venda) de um par de negociação. Mostra preços e quantidades em cada nível | | mb_get_trades | Histórico de negociações executadas recentemente. Útil para ver atividade de mercado e preços praticados | | mb_get_symbols | Lista pares de negociação com metadados (tipo de ativo, preços, volumes). Por padrão retorna apenas pares BRL em páginas de 200. Suporta paginação e filtro por símbolo específico | | mb_get_tickers | Cotações atuais: último preço, melhor compra, melhor venda, máxima, mínima, abertura e volume 24h | | mb_get_candles | Dados OHLCV (abertura, máxima, mínima, fechamento, volume) para gráficos e análise técnica. Resoluções: 1m, 15m, 1h, 3h, 1d, 1w, 1M | | mb_get_asset_fees | Taxas de depósito e saque por ativo, incluindo mínimos e confirmações necessárias por rede blockchain | | mb_get_asset_networks | Redes blockchain disponíveis para um ativo (ex: USDT pode ser sacado via Ethereum, Stellar, etc.) |

Conta (requer autenticação)

Ferramentas de consulta da sua conta. Requerem MB_API_KEY e MB_API_SECRET.

| Ferramenta | Descrição | | ---------- | --------- | | mb_list_accounts | Lista todas as suas contas/carteiras no Mercado Bitcoin. Retorna IDs necessários para outras operações | | mb_get_balances | Saldos dos seus ativos: disponível, em ordens abertas (bloqueado) e total. Por padrão exibe apenas ativos com saldo | | mb_get_tier | Nível de tier da conta — níveis mais altos possuem taxas de negociação menores | | mb_get_trading_fees | Taxas de maker (quem coloca ordem no livro) e taker (quem executa ordem existente) para um par específico | | mb_get_positions | Posições abertas com preço médio de entrada, quantidade e lado (compra/venda). Útil para análise de portfólio e P&L | | mb_internal_transfer | Transferência de ativos entre suas próprias sub-contas no Mercado Bitcoin. Requer confirmação |

Negociação (requer autenticação + modo trading ou full)

Ferramentas de negociação. Todas as operações que movem dinheiro passam pelo fluxo de confirmação em dois passos.

| Ferramenta | Descrição | | ---------- | --------- | | mb_place_order | Cria uma ordem de compra ou venda. Aceita valor em reais (cost, ex: "compre R$ 500 de BTC") ou quantidade (qty, ex: "compre 3 unidades"). Tipos: market, limit, stoplimit e post-only. Requer confirmação | | mb_list_orders | Lista ordens de um par específico com filtros: status, lado (compra/venda), período | | mb_get_order | Detalhes completos de uma ordem: execuções parciais (fills), preço médio, taxas cobradas | | mb_cancel_order | Cancela uma ordem aberta específica. Requer confirmação | | mb_cancel_all_orders | Cancela TODAS as ordens abertas da conta (opcionalmente filtradas por par). Operação perigosa — requer confirmação | | mb_list_all_orders | Lista ordens em TODOS os pares de negociação da conta |

Carteira (requer autenticação + modo full)

Ferramentas de gestão de carteira, depósitos e saques. Disponíveis apenas no modo full.

| Ferramenta | Descrição | | ---------- | --------- | | mb_create_account | Cria uma nova sub-conta (carteira) para separar fundos por estratégia. Requer confirmação | | mb_list_deposits | Histórico de depósitos de criptoativos: valores, confirmações, status, IDs de transação | | mb_get_deposit_addresses | Endereços para receber depósitos de criptoativos, incluindo QR codes. Especifique a rede para ativos multi-rede | | mb_list_fiat_deposits | Histórico de depósitos em BRL via PIX: valores, status, banco de origem | | mb_withdraw | Saque de criptoativos ou BRL. Operação de mais alto risco. Apenas para endereços/contas pré-cadastrados como "confiáveis" no Mercado Bitcoin. Requer confirmação | | mb_list_withdrawals | Histórico de saques: valores, status (aberto/concluído/cancelado), destinos | | mb_get_withdrawal | Detalhes de um saque específico por ID | | mb_get_withdraw_limits | Limites de saque por ativo | | mb_get_brl_withdraw_config | Configuração de saque em BRL: limites mínimo/máximo, limite utilizado e estrutura de taxas | | mb_list_withdraw_addresses | Lista de endereços crypto pré-cadastrados como "confiáveis" para saques | | mb_list_bank_accounts | Lista de contas bancárias pré-cadastradas para saques em BRL |

Casos de Uso

1. Monitoramento de Portfólio

"Qual é meu saldo atual? Quanto tenho de Bitcoin e Ethereum?"

A IA usa mb_list_accounts para encontrar seu ID de conta, depois mb_get_balances para listar todos os saldos. Combina com mb_get_tickers para calcular o valor total em BRL.

2. Consulta de Preços e Mercado

"Qual o preço atual do Bitcoin? Como ele variou nos últimos 7 dias?"

A IA usa mb_get_tickers para o preço atual e mb_get_candles com resolução diária para o histórico. Pode analisar tendências, suportes e resistências.

3. Compra por Valor em Reais

"Compre R$ 500 de Solana a mercado"

A IA usa mb_place_order com cost=500. O MCP consulta a cotação atual, calcula a quantidade equivalente e mostra a prévia:

CONFIRMAÇÃO NECESSÁRIA: Criar Ordem
  Símbolo: SOL-BRL
  Lado: COMPRA
  Tipo: market
  Custo: R$ 500,00
  Preço ask usado: R$ 812,50
  Qtd calculada: 0.61538461
  AVISO: O preço pode variar entre esta prévia e a execução (slippage)

Para prosseguir, confirme a operação.

Somente após sua aprovação a ordem é executada.

4. Compra por Quantidade

"Compre 3 unidades da Renda Fixa Digital RFDB11-BRL"

A IA usa mb_place_order com qty=3. Ideal para ativos que fazem mais sentido em unidades inteiras, como Renda Fixa Digital, Renda Variável Digital e Fan Tokens.

5. Venda com Limite de Preço

"Coloque uma ordem de venda de 0.01 BTC a R$ 350.000"

A IA usa mb_place_order com type=limit, side=sell, qty=0.01, limitPrice=350000. A ordem ficará no livro até ser executada ou cancelada.

6. Acompanhamento de Ordens

"Quais são minhas ordens abertas?"

A IA usa mb_list_all_orders com status=working para listar todas as ordens pendentes em todos os pares.

7. Gestão de Risco por Agente Autônomo

Um agente OpenClaw ou Claude Code pode ser configurado para:

• Monitorar preços periodicamente via mb_get_tickers
• Colocar ordens de compra quando um ativo atinge um preço alvo
• Cancelar ordens que não foram executadas após certo tempo
• Respeitar limites configurados em MB_MAX_ORDER_BRL e MB_DAILY_LIMIT_BRL

8. Consulta de Taxas Antes de Operar

"Quais as taxas para negociar ETH-BRL e para sacar ETH?"

A IA usa mb_get_trading_fees para taxas de negociação (maker/taker) e mb_get_asset_fees para taxas de saque por rede.

Desenvolvimento

git clone https://github.com/RodrigoFlorencio86/mcp-mercado-bitcoin.git
cd mcp-mercado-bitcoin
npm install
npm run build

Testar com o MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Aviso Final

Este projeto é independente e não possui vínculo, endosso ou afiliação com o Mercado Bitcoin. O nome "Mercado Bitcoin" é utilizado apenas para identificar a plataforma com a qual o MCP se integra.

O uso deste software implica na aceitação integral de todos os riscos descritos neste documento. Você é o único responsável por suas decisões de investimento e pelo uso que faz desta ferramenta.

DYOR — Faça sua própria pesquisa. Invista com responsabilidade.

Licença

MIT — veja o arquivo LICENSE para detalhes.