BNBChain MCP

BNBChain MCP (Model Context Protocol)

Um kit de ferramentas poderoso para interagir com a BNB Chain e outras redes compatíveis com EVM por meio de processamento de linguagem natural e assistência de IA.

Descrição

BNBChain MCP é uma implementação do Model Context Protocol que permite interação perfeita com redes blockchain por meio de interfaces alimentadas por IA. Ele fornece um conjunto abrangente de ferramentas e recursos para desenvolvimento blockchain, interação com contratos inteligentes e gerenciamento de rede.

Módulos Principais

O projeto está organizado em vários módulos principais:

• Blocks: Consultar e gerenciar blocos blockchain
• Contracts: Interagir com contratos inteligentes
• Network: Informações e gerenciamento de rede
• NFT: Operações com NFT (ERC721/ERC1155)
• Tokens: Operações com tokens (ERC20)
• Transactions: Gerenciamento de transações
• Wallet: Operações e gerenciamento de carteira
• Common: Utilitários e tipos compartilhados
• Greenfield: Suporte a operações de gerenciamento de arquivos na rede Greenfield, incluindo upload, download e gerenciamento de arquivos e buckets
• Recursos adicionais em breve (Greenfield, Swap, Bridge, etc.)
• Agents (ERC-8004): Registrar e resolver identidades de agentes de IA on-chain (ERC-8004 Trustless Agents) na BSC e na BSC Testnet

Notas Importantes

Não recomendamos implantar este MCP Server na internet pública. (1) O endpoint SSE não possui autenticação — qualquer pessoa que consiga acessá-lo pode usar o servidor. (2) Não existe um serviço centralizado que guarde chaves privadas ou fundos; chaves e assinaturas são responsabilidade do cliente. Se você ainda precisar implantá-lo publicamente, adicione uma camada de autenticação na frente (por exemplo, chaves de API, JWT ou um proxy reverso com autenticação), ou implante uma versão sem chave que exponha apenas ferramentas somente leitura ou não sensíveis.

Credenciais: Prefira definir PRIVATE_KEY no ambiente do servidor MCP. Não passe a chave privada em parâmetros de ferramentas quando for evitável, pois ela pode ser armazenada no histórico de conversas, logs do cliente ou logs de solicitações e levar à exposição.

Confirmação de transferência e pagamento

As ferramentas de transferência e pagamento (por exemplo, transfer_native_token, transfer_erc20, approve_token_spending, transfer_nft, transfer_erc1155, gnfd_deposit_to_payment, gnfd_withdraw_from_payment, gnfd_create_payment_account) usam um fluxo de pré-visualização e confirmação por padrão, para que nenhum fundo seja movido até que o usuário confirme explicitamente.

• Comportamento padrão: Chamar uma ferramenta de transferência ou pagamento retorna uma pré-visualização (destinatário, valor, rede, etc.) e um confirmToken de curta duração. Nenhuma transação é enviada. Para executar, chame a ferramenta confirm_transfer com esse confirmToken e seu privateKey. O token expira após 5 minutos.
• Pular confirmação (por chamada): Passe skipConfirmation: true nos argumentos da ferramenta quando o chamador já confirmou ou quando estiver executando em um script automatizado. A ferramenta será executada imediatamente e retornará o resultado da transação.
• Pular confirmação (em todo o servidor): Defina a variável de ambiente BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true para que todas as ferramentas de transferência/pagamento sejam executadas imediatamente sem retornar uma pré-visualização. Use isso em ambientes headless ou com scripts onde você não precisa de uma etapa de confirmação.

Exemplo de fluxo com confirmação:

1. Chame transfer_native_token com toAddress, amount, network (e opcionalmente privateKey). Não defina skipConfirmation.
2. O servidor retorna { preview: { toAddress, amount, network }, confirmToken: "...", message: "..." }.
3. Revise a pré-visualização e, em seguida, chame confirm_transfer com confirmToken e privateKey para executar a transferência.

Integração com Cursor

Para conectar-se ao servidor MCP a partir do Cursor:

1. Abra o Cursor e vá para Configurações (ícone de engrenagem no canto superior direito)
2. Clique em "MCP" na barra lateral esquerda
3. Clique em "Add new global MCP server"
4. Insira os seguintes detalhes:

Modo padrão

{
  "mcpServers": {
    "bnbchain-mcp": {
      "command": "npx",
      "args": ["-y", "@bnb-chain/mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here. (optional)",
        "BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}

• PRIVATE_KEY: Opcional. Prefira definir aqui em vez de passar nos parâmetros da ferramenta.
• BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION: Opcional. Defina como "true" para fazer todas as ferramentas de transferência/pagamento executarem imediatamente (sem etapa de pré-visualização). O padrão "false" usa o fluxo de pré-visualização e confirmação.

Modo SSE

{
  "mcpServers": {
    "bnbchain-mcp": {
      "command": "npx",
      "args": ["-y", "@bnb-chain/mcp@latest", "--sse"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here. (optional)",
        "BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}

Integração com Claude Desktop

Para conectar-se ao servidor MCP a partir do Claude Desktop:

1. Abra o Claude Desktop e vá para Configurações
2. Clique em "Developer" na barra lateral esquerda
3. Clique no botão "Edit Config"
4. Adicione a seguinte configuração ao arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "bnbchain-mcp": {
      "command": "npx",
      "args": ["-y", "@bnb-chain/mcp@latest"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION": "false"
      }
    }
  }
}

Env opcional: BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true para executar transferências imediatamente sem pré-visualização/confirmação.

5. Salve o arquivo e reinicie o Claude Desktop

Uma vez conectado, você pode usar todos os prompts e ferramentas do MCP diretamente em suas conversas no Claude Desktop. Por exemplo:

• "Analise este endereço: 0x123..."
• "Explique o conceito de gas no EVM"
• "Verifique o bloco mais recente na BSC"

Integração com Outros Clientes

Se você quiser integrar o BNBChain MCP ao seu próprio cliente, consulte o diretório examples para obter informações mais detalhadas e implementações de referência.

Os exemplos demonstram:

• Como configurar o cliente MCP
• Autenticação e configuração
• Fazer chamadas de API para interagir com redes blockchain
• Tratamento de respostas e erros
• Melhores práticas para integração

Desenvolvimento Local

Pré-requisitos

• bun v1.2.10 ou superior
• Node.js v17 ou superior

Início Rápido

1. Clone o repositório:

git clone https://github.com/bnb-chain/bnbchain-mcp.git
cd bnbchain-mcp

2. Configure as variáveis de ambiente:

cp .env.example .env

Edite o arquivo .env com sua configuração:

• PRIVATE_KEY: Sua chave privada da carteira (necessária para operações de transação)
• LOG_LEVEL: Defina o nível de log (DEBUG, INFO, WARN, ERROR)
• PORT: Número da porta do servidor (padrão: 3001)

3. Instale as dependências e inicie o servidor de desenvolvimento:

# Install project dependencies
bun install

# Start the development server
bun dev:sse

Testando com Clientes MCP

Configure o servidor local em seus clientes MCP usando este modelo:

{
  "mcpServers": {
    "bnbchain-mcp": {
      "url": "http://localhost:3001/sse",
      "env": {
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

Testando com Web UI

Usamos @modelcontextprotocol/inspector para testes. Inicie a UI de teste:

bun run test

Scripts Disponíveis

• bun dev:sse: Iniciar servidor de desenvolvimento com recarga automática
• bun build: Compilar o projeto
• bun test: Executar a suíte de testes

Prompts e Ferramentas Disponíveis

Prompts

Nome	Descrição
analyze_block	Analisar um bloco e fornecer informações detalhadas sobre seu conteúdo
analyze_transaction	Analisar uma transação específica
analyze_address	Analisar um endereço EVM
interact_with_contract	Obter orientação sobre como interagir com um contrato inteligente
explain_evm_concept	Obter uma explicação sobre um conceito EVM
compare_networks	Comparar diferentes redes compatíveis com EVM
analyze_token	Analisar um token ERC20 ou NFT
how_to_register_mcp_as_erc8004_agent	Obter orientação sobre como registrar um servidor MCP como um agente ERC-8004

Ferramentas

Nome	Descrição
get_block_by_hash	Obter um bloco pelo hash
get_block_by_number	Obter um bloco pelo número
get_latest_block	Obter o bloco mais recente
get_transaction	Obter informações detalhadas sobre uma transação específica pelo hash
get_transaction_receipt	Obter o recibo de uma transação pelo hash
estimate_gas	Estimar o custo de gas para uma transação
transfer_native_token	Transferir tokens nativos (BNB, ETH, MATIC, etc.) para um endereço
approve_token_spending	Aprovar outro endereço para gastar seus tokens ERC20
transfer_nft	Transferir um NFT (token ERC721) de um endereço para outro
transfer_erc1155	Transferir tokens ERC1155 para outro endereço
transfer_erc20	Transferir tokens ERC20 para um endereço
get_address_from_private_key	Obter o endereço EVM derivado de uma chave privada
get_chain_info	Obter informações da cadeia para uma rede específica
get_supported_networks	Obter lista de redes suportadas
resolve_ens	Resolver um nome ENS para um endereço EVM
is_contract	Verificar se um endereço é um contrato inteligente ou uma conta de propriedade externa (EOA)
read_contract	Ler dados de um contrato inteligente chamando uma função view/pure
write_contract	Escrever dados em um contrato inteligente chamando uma função que altera o estado
get_erc20_token_info	Obter informações do token ERC20
get_native_balance	Obter saldo de token nativo para um endereço
get_erc20_balance	Obter saldo de token ERC20 para um endereço
get_nft_info	Obter informações detalhadas sobre um NFT específico
check_nft_ownership	Verificar se um endereço possui um NFT específico
get_erc1155_token_metadata	Obter os metadados de um token ERC1155
get_nft_balance	Obter o número total de NFTs pertencentes a um endereço de uma coleção específica
get_erc1155_balance	Obter o saldo de um ID de token ERC1155 específico pertencente a um endereço

Ferramentas de Agente ERC-8004

Registre e resolva agentes de IA no ERC-8004 Identity Registry (Trustless Agents). Redes suportadas: BSC (56), BSC Testnet (97), Ethereum, Base, Polygon e suas testnets onde o registro oficial está implantado. O agentURI deve apontar para um arquivo de metadados JSON seguindo o Agent Metadata Profile (nome, descrição, imagem e services como endpoint MCP).

Nome	Descrição
register_erc8004_agent	Registrar um agente no ERC-8004 Identity Registry; retorna o ID do agente
set_erc8004_agent_uri	Atualizar o URI de metadados para um agente ERC-8004 existente (somente proprietário)
get_erc8004_agent	Obter informações do agente (proprietário e tokenURI) do Identity Registry
get_erc8004_agent_wallet	Obter a carteira de pagamento verificada para um agente (para x402 / pagamentos)

Ferramentas Greenfield

Nome	Descrição
gnfd_get_bucket_info	Obter informações detalhadas sobre um bucket específico
gnfd_list_buckets	Listar todos os buckets pertencentes a um endereço
gnfd_create_bucket	Criar um novo bucket
gnfd_delete_bucket	Excluir um bucket
gnfd_get_object_info	Obter informações detalhadas sobre um objeto específico
gnfd_list_objects	Listar todos os objetos em um bucket
gnfd_upload_object	Enviar um objeto para um bucket
gnfd_download_object	Baixar um objeto de um bucket
gnfd_delete_object	Excluir um objeto de um bucket
gnfd_create_folder	Criar uma pasta em um bucket
gnfd_get_account_balance	Obter o saldo de uma conta
gnfd_deposit_to_payment	Depositar fundos em uma conta de pagamento
gnfd_withdraw_from_payment	Retirar fundos de uma conta de pagamento
gnfd_disable_refund	Desativar reembolso para uma conta de pagamento (IRREVERSÍVEL)
gnfd_get_payment_accounts	Listar todas as contas de pagamento pertencentes a um endereço
gnfd_get_payment_account_info	Obter informações detalhadas sobre uma conta de pagamento
gnfd_create_payment	Criar uma nova conta de pagamento
gnfd_get_payment_balance	Obter saldo da conta de pagamento

Redes Suportadas

Suporta BSC, opBNB, Greenfield, Ethereum e outras redes principais compatíveis com EVM. Para mais detalhes, consulte src/evm/chains.ts.

Registro de agente ERC-8004 está disponível em cadeias onde o registro oficial está implantado: BSC (56), BSC Testnet (97), Ethereum (1), Sepolia (11155111), Base (8453), Base Sepolia (84532), Polygon (137), Polygon Amoy (80002), Arbitrum (42161), Arbitrum Sepolia (421614). A chave privada é usada apenas para assinar a transação de registro ou atualização e não é armazenada nem registrada em logs.

Contribuindo

Aceitamos contribuições para o BNBChain MCP! Veja como você pode ajudar:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça commit das suas alterações
4. Envie para o seu branch
5. Crie um Pull Request

Certifique-se de que seu código segue nossos padrões de codificação e inclui testes apropriados.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Referências e Agradecimentos

Este projeto foi construído com base e inspirado nos seguintes projetos de código aberto:

• TermiX-official/bsc-mcp - Implementação original do BSC MCP
• mcpdotdirect/evm-mcp-server - Implementação de servidor MCP compatível com EVM

Estendemos nossa gratidão aos autores originais por suas contribuições ao ecossistema blockchain.