Bitcoin SV MCP Server

Uma coleção de ferramentas para interagir com a blockchain Bitcoin SV (BSV), incluindo carteira, ordinais e funções utilitárias.

GitHub
22
Experimente este MCPPatrocinado

Documentação

BSV MCP

O BSV MCP conecta seu assistente de IA ao Bitcoin SV. Peça para verificar uma transação, mostrar seu saldo, enviar um pagamento ou criar e negociar ordinais (conteúdo registrado no blockchain).

Documentação · Todas as ferramentas · npm · Problemas

Instalação

Instale o Bun para executar o servidor e o Node.js para os comandos npx abaixo, e então adicione-o ao seu cliente:

# Codex
codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Claude Code
claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Grok Build
grok plugin install b-open-io/bsv-mcp --trust

Escolha um comando. Para Cursor ou Claude Desktop, use esta configuração de servidor:

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

Reinicie seu cliente e pergunte: “Execute bsv_status e explique o que está disponível.” O stdio local não precisa de conta Sigma nem de login OAuth. Também é o padrão quando nenhum transporte é especificado. O HTTP auto-hospedado existente permanece opcional por meio de TRANSPORT=http; o endpoint hospedado implantado não foi alterado.

Para o plugin de desktop do Codex, adicione b-open-io/claude-plugins no mercado de plugins e instale o BSV MCP. O plugin inicia o executável npm local e requer Node.js e Bun. Os plugins Claude Code e Grok incluem o servidor local e requerem Bun. Escolha um registro para evitar ferramentas duplicadas.

Conecte uma carteira

Peça ao seu assistente para executar wallet_onboarding. Crie, importe ou desbloqueie um Vault no navegador local. Faça backup antes de financiar. Insira senhas apenas na interface de configuração local, nunca no chat. Após reiniciar o servidor, desbloqueie novamente.

Para usar uma carteira BRC-100 existente, configure a API de assinatura dela:

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"],
      "env": {
        "BRC100_WALLET_URL": "http://127.0.0.1:3321",
        "BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
      }
    }
  }
}

A carteira mantém suas chaves e controla as solicitações de permissão. A API de assinatura dela é separada de um endpoint de armazenamento de carteira. Consulte configuração da carteira para configurações de rede, seleção de conta e funções de projeto.

O pacote também inclui o lançador bsv-mcp-local baseado em Bun para configurações externas explícitas, embutidas legadas e de projeto. Exemplos de checkout do código-fonte estão em o guia de instalação.

Compatibilidade com o protocolo MCP

A revisão do protocolo 2026-07-28 é preferida, com clientes 2025 suportados aceitos automaticamente em stdio e HTTP. Nenhuma substituição de compatibilidade é necessária. Defina MCP_LEGACY_COMPATIBILITY=false apenas para exigir clientes modernos. Essa configuração também é repassada pelo lançador local. O cliente desktop instalado foi verificado usando solicitações legadas; o suporte moderno é testado separadamente.

Clientes modernos suportam operações de carteira e aprovação com escopo de solicitação. As continuações de aprovação retêm a operação original e a vinculam ao usuário autenticado, aos argumentos e à expiração. Recusar, cancelar ou revogar a sessão interrompe a operação; reproduzir uma continuação não repete uma transação. Um cliente sem elicitação de formulário não pode aprovar um gasto. Carteiras externas mantêm o próprio fluxo de permissão do assinante. A rota hospedada expõe apenas leituras públicas.

Para o cliente dividido do SDK v2:

const client = new Client(
  { name: "my-app", version: "1" },
  { versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
);

Registre um manipulador de aprovação humano real antes de usar ferramentas que dependem de aprovação. A compatibilidade com o protocolo legado é habilitada por padrão; o cliente conectado deve suportar o fluxo de aprovação necessário para a ferramenta solicitada.

O catálogo completo de ferramentas permanece o padrão e é derivado de capacidade: o modo de carteira, os módulos habilitados, o contexto da conta e o perfil selecionado determinam o que tools/list retorna. O manifesto verificado é uma linha de base sintética para um servidor configurado, não uma promessa de uma contagem padrão fixa. Defina MCP_TOOL_CATALOG=compact apenas para optar por famílias de leitura limitadas; o modo compacto usa os mesmos manipuladores subjacentes. A disponibilidade das ferramentas ainda depende do modo de carteira e dos módulos habilitados. Suas famílias de leitura de linha de base são bsv_read, ordinals_read, wallet_read e utility, cada uma com uma enumeração de operação limitada; operações desconhecidas são rejeitadas. Sessões elegíveis também expõem famílias mutáveis separadas wallet_setup e wallet_payments. Consulte o guia de suporte ao protocolo do cliente MCP para os limites de operação por família, contratos de endpoint, compatibilidade com MCP Apps e status de validação.

Social

Duas ferramentas cobrem operações sociais nos catálogos completo e compacto:

  • bsocial_read: postagens, respostas, pesquisa, curtidas, amigos, canais, mensagens, vídeos e histórico de ações brutas.
  • bsocial_publish: postagens/respostas, repostagens, curtidas/descurtidas, seguir/deixar de seguir, registros de amizade, mensagens e registros de vídeo. Tags e anexos usam saídas separadas e assinadas de forma independente.
{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}

A pré-visualização retorna saídas não assinadas sem usar chaves ou gastar. Remova preview para publicar por meio das permissões existentes da carteira de identidade selecionada. As mensagens são públicas, a menos que o conteúdo tenha sido criptografado antes; um contexto de destinatário não as criptografa. Registros de amizade anunciam uma chave pública de comunicação de um fluxo de acordo de chave estabelecido.

Consulte o guia social para exemplos e migração dos nomes antigos de ferramentas. PUBLIC_BMAP_URL é a raiz do servidor indexador (com rotas /social e /q), não uma carteira ou API de identidade. Registros brutos de seguir/deixar de seguir são histórico de eventos, não uma afirmação sobre o estado atual do relacionamento.

Modos de carteira local

O modo externo conecta-se a um assinante BRC-100 existente. O assinante mantém as chaves privadas, o armazenamento da carteira e as decisões de permissão; o BSV MCP recebe apenas a interface do assinante do SDK. O modo embutido usa uma carteira Vault local criptografada. A tela de carteira pronta exibe uma nuvem interativa das ferramentas disponíveis da sessão conectada, gerada a partir do catálogo ao vivo.

Quando a configuração for necessária, wallet_onboarding abre o fluxo privado do navegador para criar, importar ou desbloqueá-la. O banco de dados da conta selecionada e a configuração de armazenamento permanecem em uso. O modo embutido de conta existente do lançador ainda fornece BSV_MCP_PASSWORD em tempo de execução. O modo de projeto abre todas as funções explicitamente atribuídas: payments, identity-signing, one-sat e encryption. Ele requer seletores de projeto emparelhados e BSV_MCP_PASSWORD em tempo de execução; defina VAULT_PATH quando o módulo Vault não fornecer um caminho padrão. As vinculações fixam a chave pública selecionada e suportam chaves diretas, filhos BRC-42 e folhas de perfil BRC-157/Yours. Alterar a vinculação do projeto ou expirar sua sessão revoga os identificadores capturados. As chaves derivadas têm armazenamento separado; selecionar a raiz de pagamento da conta mantém seu banco de dados existente e o prefixo de depósito.

As ferramentas BRC-100 aceitam walletRole (payments, identity, ordinals ou encryption). Os padrões de método selecionam a função correspondente, e as continuações de ação de assinar/cancelar retêm sua carteira de origem e usuário autenticado. Uma função não atribuída falha em vez de emprestar outra chave. As ferramentas BAP usam a carteira de identidade para publicação, rotação, atestados e perfis sem exportar um xprv. Essa carteira também financia essas transações e retém registros BAP. Postagens BSocial assinadas e inscrições SIGMA usam a identidade configurada.

Registros externos podem usar o mesmo par raiz/ID de projeto para derivar uma origem de permissão isolada, sem senha do Vault. O BRC100_WALLET_PUBLIC_KEY opcional fixa a identidade do assinante. BRC100_WALLET_ROLES é um objeto JSON que seleciona endpoints de função independentes e fixações de chave pública; consulte configuração do assinante externo. O lançador de código-fonte aceita external --project-root /absolute/project --project-id project.example. Ele usa transmissão desabilitada por padrão; defina DISABLE_BROADCASTING=false em seu ambiente de execução para habilitar ferramentas de transação com a aprovação do assinante.

Cada modo tem seu próprio ambiente de processo e deve ser registrado como um servidor separado quando você precisar alternar entre eles. Use apenas os registros necessários para o projeto.

Carteiras embutidas podem listar pagamentos PeerPay pendentes e receber um pagamento selecionado com wallet_peerPayments. O recebimento requer um ID de mensagem e reconhece a mensagem somente após a carteira aceitá-la. Essas operações não pagam taxas de serviço do MessageBox. Assinantes externos e Droplit não expõem essa ferramenta. Sessões de projeto exigem uma função de pagamento atribuída.

Encontre uma habilidade

Use utils_find_skills com uma consulta curta de palavra-chave para encontrar habilidades no catálogo bOpen. Ele retorna até cinco descrições e links para arquivos SKILL.md versionados. Ele não baixa conteúdos de habilidades nem instala plugins. No modo compacto, selecione utils_find_skills na ferramenta utility.

Os prompts estáticos de tutorial e o catálogo de recursos BRC/BitCom foram aposentados. Use o localizador de habilidades para essas referências. O changelog, a documentação do JungleBus e o recurso do aplicativo de painel permanecem disponíveis.

Traga sua carteira e infraestrutura

Conecte uma carteira existente compatível com BRC100_WALLET_URL, ou use a configuração do navegador Vault local (wallet_onboarding). BSV_MCP_PASSWORD é apenas para agentes headless: defina-o no ambiente de processo dessa sessão, nunca na configuração do cliente MCP. PRIVATE_KEY_WIF e IDENTITY_KEY_WIF são fontes de migração, não chaves de assinatura ativas; importe-os para o Vault e remova as cópias em texto simples. A inicialização nunca cria chaves. Consulte o guia de configuração da carteira para a API de carteira e a configuração necessárias.

O backend padrão da API 1Sat é https://api.1sat.app. Novas contas embutidas de mainnet usam https://wallet.1sat.app para armazenamento de carteira por padrão; contas de testnet não selecionam um provedor de armazenamento remoto, a menos que configurado. Substitua ONESAT_API_URL para serviços de API e REMOTE_STORAGE_URL para armazenamento de carteira; essas são configurações separadas. As ferramentas disponíveis dependem do modo de carteira e dos módulos habilitados.

Desenvolvimento

bun install
bun run dev          # Website
bun run build:all    # MCP server and dashboard
# Supply BRC100_WALLET_URL in the host environment before this launch.
bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
bun test

Software experimental; as APIs podem mudar. Mantenha um backup da carteira. Se uma solicitação de transação expirar, verifique se ela foi bem-sucedida antes de enviá-la novamente. Licença MIT.

Preparando um pacote de lançamento

package.json "files" é o tarball. prepack executa bun run build:all. Publique com bun publish. As bibliotecas em tempo de compilação são devDependencies; os consumidores recebem os arquivos dist/ agrupados, não uma segunda cópia da árvore de código-fonte.