Bitcoin & Lightning Network

₿itcoin & Lightning Network MCP Server

Visão Geral

Um servidor Model Context Protocol (MCP) que permite que modelos de IA interajam com a Bitcoin e a Lightning Network, permitindo-lhes gerar chaves, validar endereços, decodificar transações, consultar a blockchain e muito mais.

🎮 Demonstração

Demonstração do Claude Vídeo	Demonstração do Goose Vídeo

💼 Índice

• ₿itcoin & Lightning Network MCP Server
  • Visão Geral
  • 🎮 Demonstração
  • 💼 Índice
  • 🔧 Recursos
  • 🔑 Integração com Claude Desktop
    • Testando a Integração com Claude Desktop
  • 🦆 Integração com Goose
    • Usando STDIO (Extensão Local)
      • Usando SSE (Extensão Remota)
  • 📦 Configuração de Desenvolvimento
    • Configuração da Lightning Network (Opcional)
  • 📦 Ferramentas Disponíveis
  • 🚨 Tratamento de Erros
  • 🤝 Contribuindo
  • 📝 Licença

🔧 Recursos

• Geração de Chaves: Crie novos pares de chaves Bitcoin — incluindo endereço, chave pública e chave privada (WIF).
• Validação de Endereço: Valide a correção de um endereço Bitcoin.
• Decodificação de Transações: Analise uma transação Bitcoin bruta e exiba seus detalhes em um formato legível por humanos.
• Consultas à Blockchain:
  • Bloco Mais Recente: Recupere detalhes sobre o bloco mais recente (hash, altura, timestamp, contagem de transações, etc.).
  • Detalhes da Transação: Obtenha informações detalhadas sobre uma transação usando seu TXID.
• Lightning Network:
  • Decodificação de Faturas: Analise uma fatura Lightning BOLT11 e exiba informações legíveis por humanos.
  • Pagamento: Pague uma fatura Lightning diretamente da sua carteira LNBits.

🔑 Integração com Claude Desktop

Para usar o servidor Bitcoin MCP com o Claude Desktop (aplicativo de desktop da Anthropic para Claude), siga estas etapas:

1. Baixe e instale o Claude Desktop: Visite a página oficial de downloads do Claude Desktop e obtenha o aplicativo para o seu sistema operacional (macOS ou Windows) (Instalando o Claude para Desktop | Central de Ajuda da Anthropic). Instale o aplicativo e certifique-se de estar usando a versão mais recente (você pode verificar atualizações no menu do aplicativo).

2. Configure o Claude Desktop para usar o servidor Bitcoin MCP: Abra o arquivo de configuração do Claude Desktop (ele é criado quando você edita as configurações pela primeira vez no Claude Desktop):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
     Adicione uma entrada para o servidor Bitcoin MCP neste arquivo JSON na seção "mcpServers". Por exemplo:

   {
     "mcpServers": {
       "bitcoin-mcp": {
         "command": "npx",
         "args": ["-y", "bitcoin-mcp@latest"]
       }
     }
   }
   

   No trecho acima, "bitcoin-mcp" é um identificador para o servidor (você pode nomeá-lo como quiser). O command é definido para executar o comando npx, e args aponta para o caminho do script do seu servidor Bitcoin MCP ou o comando para executar o servidor.

3. Reinicie o Claude Desktop: Salve o arquivo claude_desktop_config.json e depois feche e reabra o Claude Desktop. Na próxima inicialização, o Claude iniciará automaticamente o servidor Bitcoin MCP conforme configurado. Se o Claude Desktop estava em execução, você precisa reiniciá-lo para que as alterações tenham efeito.

Testando a Integração com Claude Desktop

Depois que o Claude Desktop for reiniciado, você pode testar se o servidor Bitcoin MCP está funcionando corretamente:

• Pergunte ao Claude uma pergunta de exemplo relacionada ao Bitcoin. Por exemplo, tente perguntar: "Qual é o bloco mais recente na rede Bitcoin?" Se a integração for bem-sucedida, a resposta do Claude deve incluir o bloco mais recente obtido via servidor MCP, em vez de um "não sei" ou uma resposta genérica. Você também pode tentar outras consultas como "Dê-me informações sobre a transação com TXID abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890." O Claude deve usar as ferramentas do servidor MCP para recuperar os dados e responder à sua pergunta.

• Verifique a resposta: O Claude deve retornar uma resposta detalhada (por exemplo, o bloco mais recente na rede Bitcoin) sem erros. Se você receber uma mensagem de erro ou nenhuma resposta útil, o servidor MCP pode não estar conectado corretamente.

• Verifique os logs do Claude (se necessário): O Claude Desktop fornece arquivos de log que podem ajudar a depurar integrações MCP. Se a ferramenta não estiver respondendo, verifique os arquivos de log em:

  • macOS: ~/Library/Logs/Claude/
  • Windows: %APPDATA%\Claude\logs\
    Procure por mcp.log para mensagens gerais de conexão MCP, e um arquivo chamado mcp-server-bitcoin-mcp.log (ou com o nome que você usou) para a saída/erros do servidor MCP. Esses logs mostrarão se o servidor iniciou ou se houve erros (como um caminho errado ou exceções no servidor). Se você vir erros, corrija a configuração ou o ambiente conforme necessário, reinicie o Claude Desktop e teste novamente.

🦆 Integração com Goose

Goose é um framework de agente de IA de código aberto da Block que suporta extensões via Model Context Protocol. Você pode integrar o servidor Bitcoin MCP como uma extensão do Goose para permitir que o Goose interaja com a blockchain Bitcoin. O Goose suporta dois modos de integração para servidores MCP: executar o servidor como um processo local (STDIO) ou conectar-se a ele como um serviço remoto via Server-Sent Events (SSE). Abaixo estão as instruções para ambos os métodos:

Usando STDIO (Extensão Local)

Este método executa o servidor Bitcoin MCP localmente como um subprocesso do Goose, comunicando-se através da entrada/saída padrão.

1. Adicione uma nova extensão no Goose: Abra a interface de configuração do Goose. Você pode fazer isso via linha de comando executando goose configure, ou no aplicativo Goose Desktop indo em Configurações > Extensões. No menu, escolha "Adicionar Extensão." (Usando Extensões | goose)

2. Escolha o tipo de extensão – Extensão de Linha de Comando: Quando solicitado o tipo de extensão, selecione Extensão de Linha de Comando (no menu CLI ou na interface) para que o Goose saiba que deve lançar um comando local (Usando Extensões | goose) (em oposição a uma extensão embutida ou remota).

3. Insira os detalhes da extensão: Forneça um nome e comando para o servidor Bitcoin MCP:

   • Nome: Você pode chamá-lo de "bitcoin", ou qualquer identificador (será assim que você se referirá à extensão).

   • Comando: Especifique como executar o servidor MCP. Por exemplo, se você tiver o script Python, insira o comando para executá-lo. No configurador CLI, pode perguntar "Qual comando deve ser executado?" – você entraria:

     npx -y bitcoin-mcp@latest
     

     Isso diz ao Goose para lançar o servidor Bitcoin MCP (GitHub - AbdelStark/bitcoin-mcp: Bitcoin MCP Server). (Certifique-se de usar o caminho correto para o script do seu servidor ou o comando correto para executar o servidor, assim como na configuração do Claude.)

   • Normalmente, você não precisa adicionar argumentos além do caminho do script (a menos que seu servidor exija sinalizadores especiais). O comando acima usa o transporte STDIO padrão, que o Goose espera para uma extensão de linha de comando. (No arquivo de configuração do Goose, isso corresponderia a uma entrada com cmd: "npx" e args: ["-y", "bitcoin-mcp@latest"], com type: stdio indicando o modo de E/S padrão (Usando Extensões | goose).)

4. Finalize e habilite: Complete a adição da extensão. O Goose adicionará esta nova extensão à sua configuração (geralmente ~/.config/goose/config.yaml). Certifique-se de que a extensão esteja habilitada (se estiver usando o assistente CLI, ela deve estar habilitada por padrão após ser adicionada; no aplicativo Goose Desktop, você pode verificar a lista de Extensões e ativá-la se ainda não estiver (Usando Extensões | goose) (Usando Extensões | goose)).

5. Inicie uma sessão do Goose com a nova extensão: Agora você pode usar a extensão no Goose. Se estiver executando o Goose via CLI, inicie uma sessão que inclua a extensão executando:

   goose session --with-extension "bitcoin"
   

substituindo "bitcoin" pelo nome que você deu à extensão (Usando Extensões | goose). (Isso garante que a sessão carregue a extensão. Alternativamente, se a extensão estiver habilitada globalmente, o Goose Desktop ou CLI a terá automaticamente disponível em todas as sessões.)

Usando SSE (Extensão Remota)

Este método conecta o Goose a um servidor MCP já em execução via um fluxo HTTP SSE. Use isso se quiser executar o servidor Bitcoin MCP como um serviço independente (possivelmente em outra máquina ou apenas independente do Goose).

1. Inicie o servidor MCP como um serviço independente: Execute o servidor Bitcoin MCP para que ele escute conexões. Na prática, isso significa que o servidor precisa ser iniciado em um modo que sirva um endpoint HTTP para MCP. Por exemplo, você pode executar o servidor com um comando ou opção específica para escutar em uma porta (como usar os recursos de servidor web embutidos de uma biblioteca MCP ou executar sob um framework web). Certifique-se de que o servidor esteja acessível em uma URL conhecida (por exemplo, http://localhost:9000) e suporte o protocolo MCP sobre SSE.

2. Adicione uma nova extensão no Goose (Remota): Como antes, execute goose configure ou use a interface do Goose para Adicionar Extensão (Usando Extensões | goose). Desta vez, escolha Extensão Remota quando perguntado sobre o tipo de extensão (Usando Extensões | goose). Isso diz ao Goose que ele se conectará a um servidor externo via SSE.

3. Insira os detalhes da extensão remota: Dê um nome à extensão (por exemplo, "bitcoin") e forneça a URL do servidor. Para a URL, insira o endereço base onde o servidor MCP está em execução. Por exemplo, se o seu servidor estiver escutando na porta 9000 na sua máquina local, você pode inserir http://localhost:9000. O Goose tentará se conectar ao endpoint SSE do servidor MCP nesse endereço. (O Goose usa o caminho SSE padrão do MCP, que por convenção está sob a rota /mcp/sse no servidor; você geralmente só precisa fornecer o host e a porta, e o Goose cuida do resto.)

4. Habilite a extensão: Após adicionar a extensão remota, certifique-se de que ela esteja habilitada nas configurações do Goose (assim como no caso STDIO). Apenas uma das extensões STDIO ou SSE (com as mesmas ferramentas) precisa estar habilitada – se você acidentalmente habilitar tanto uma versão local quanto uma remota do mesmo servidor, talvez queira desabilitar uma para evitar confusão.

Usando a extensão Bitcoin MCP no Goose: Depois que a extensão estiver configurada (por qualquer um dos métodos acima) e habilitada, você pode interagir com o Goose e consultar dados do Bitcoin através dela. Em um novo chat ou sessão do Goose, basta fazer perguntas como faria normalmente. O Goose reconhecerá quando usar as ferramentas Bitcoin MCP para atender à sua solicitação. Por exemplo:

• "Qual é o bloco Bitcoin mais recente?"
• "Dê-me informações sobre a transação com TXID abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890."

Quando você fizer essas perguntas, o Goose invocará as ferramentas do servidor MCP e retornará a resposta (por exemplo, as informações do bloco Bitcoin mais recente). Você deve ver o Goose respondendo com informações atualizadas obtidas da blockchain Bitcoin via servidor MCP. Se o Goose não parecer usar a extensão (por exemplo, se ele responder que não consegue encontrar as informações), certifique-se de que a extensão está habilitada e que o servidor está em execução (no modo SSE para remoto). Você também pode executar a CLI do Goose com registro detalhado (verbose) para ver se ele tentou chamar a extensão. Geralmente, se configurado corretamente, o Goose descobrirá automaticamente as capacidades do servidor MCP e as usará quando relevante.

Recursos Adicionais: Para mais detalhes sobre extensões do Goose e o MCP, consulte a documentação oficial do Goose (Usando Extensões | goose). A documentação inclui uma lista de extensões integradas e da comunidade e explica como os servidores MCP se integram ao Goose. Você também pode encontrar um diretório de servidores MCP disponíveis e dicas adicionais de configuração na documentação do Goose e na documentação do Model Context Protocol. Isso pode ajudar se você quiser explorar mais extensões ou desenvolver as suas próprias.

📦 Configuração de Desenvolvimento

Encontre as instruções de configuração no guia Configuração de Desenvolvimento.

Configuração da Lightning Network (Opcional)

Para usar os recursos da Lightning Network, você precisará configurar os detalhes de conexão do LNBits. Eles são opcionais e só são necessários se você planeja usar as ferramentas da Lightning Network.

{
  "lnbitsUrl": "https://demo.lnbits.com",  
  "lnbitsAdminKey": "your_admin_key",      // Required for making payments
  "lnbitsReadKey": "your_read_key"         // Required for wallet information
}

Você pode obter esses valores:

1. Criando uma conta em LNBits
2. Criando uma nova carteira
3. Indo para as informações da API para encontrar suas chaves de API

📦 Ferramentas Disponíveis

Encontre as ferramentas disponíveis no guia Referência da API.

🚨 Tratamento de Erros

O servidor emprega tipos de erro personalizados para lidar com operações Bitcoin e consultas de blockchain. Mensagens de erro detalhadas são registradas usando Pino e incluídas nas respostas do cliente para facilitar a depuração.

🤝 Contribuindo

Contribuições e solicitações de recursos são bem-vindas! Sinta-se à vontade para enviar pull requests ou abrir issues no GitHub.

📝 Licença

Este projeto é licenciado sob a Licença MIT.