BNBChain MCP

BNBChain MCP (Model Context Protocol)

Un potente kit de herramientas para interactuar con BNB Chain y otras redes compatibles con EVM mediante procesamiento de lenguaje natural y asistencia de IA.

Descripción

BNBChain MCP es una implementación del Model Context Protocol que permite una interacción fluida con redes blockchain a través de interfaces impulsadas por IA. Proporciona un conjunto completo de herramientas y recursos para el desarrollo blockchain, la interacción con contratos inteligentes y la gestión de redes.

Módulos principales

El proyecto está organizado en varios módulos principales:

• Blocks: Consultar y gestionar bloques de blockchain
• Contracts: Interactuar con contratos inteligentes
• Network: Información y gestión de redes
• NFT: Operaciones con NFT (ERC721/ERC1155)
• Tokens: Operaciones con tokens (ERC20)
• Transactions: Gestión de transacciones
• Wallet: Operaciones y gestión de carteras
• Common: Utilidades y tipos compartidos
• Greenfield: Soporte para operaciones de gestión de archivos en la red Greenfield, incluyendo carga, descarga y gestión de archivos y buckets
• Funcionalidades adicionales próximamente (Greenfield, Swap, Bridge, etc.)
• Agents (ERC-8004): Registrar y resolver identidades de agentes de IA en cadena (ERC-8004 Trustless Agents) en BSC y BSC Testnet

Notas importantes

No recomendamos desplegar este servidor MCP en Internet público. (1) El endpoint SSE no tiene autenticación: cualquiera que pueda alcanzarlo puede usar el servidor. (2) No existe un servicio centralizado que custodie claves privadas o fondos; las claves y la firma son responsabilidad del cliente. Si aún así necesitas desplegarlo públicamente, añade una capa de autenticación delante (por ejemplo, claves API, JWT o un proxy inverso con autenticación), o despliega una versión sin claves que solo exponga herramientas de solo lectura o no sensibles.

Credenciales: Prefiere configurar PRIVATE_KEY en el entorno del servidor MCP. No pases la clave privada en los parámetros de las herramientas cuando sea evitable, ya que podría almacenarse en el historial de conversación, registros del cliente o registros de solicitudes y provocar una exposición.

Confirmación de transferencias y pagos

Las herramientas de transferencia y pago (por ejemplo, transfer_native_token, transfer_erc20, approve_token_spending, transfer_nft, transfer_erc1155, gnfd_deposit_to_payment, gnfd_withdraw_from_payment, gnfd_create_payment_account) utilizan un flujo de vista previa y confirmación por defecto, de modo que no se mueven fondos hasta que el usuario confirme explícitamente.

• Comportamiento predeterminado: Llamar a una herramienta de transferencia o pago devuelve una vista previa (destinatario, importe, red, etc.) y un confirmToken de corta duración. No se envía ninguna transacción. Para ejecutarla, llama a la herramienta confirm_transfer con ese confirmToken y tu privateKey. El token caduca después de 5 minutos.
• Omitir confirmación (por llamada): Pasa skipConfirmation: true en los argumentos de la herramienta cuando el llamador ya haya confirmado o cuando se ejecute en un script automatizado. La herramienta se ejecutará inmediatamente y devolverá el resultado de la transacción.
• Omitir confirmación (en todo el servidor): Configura la variable de entorno BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true para que todas las herramientas de transferencia/pago se ejecuten inmediatamente sin devolver una vista previa. Úsalo en entornos sin interfaz o con scripts donde no necesites un paso de confirmación.

Ejemplo de flujo con confirmación:

1. Llama a transfer_native_token con toAddress, amount, network (y opcionalmente privateKey). No configures skipConfirmation.
2. El servidor devuelve { preview: { toAddress, amount, network }, confirmToken: "...", message: "..." }.
3. Revisa la vista previa y luego llama a confirm_transfer con confirmToken y privateKey para ejecutar la transferencia.

Integración con Cursor

Para conectarte al servidor MCP desde Cursor:

1. Abre Cursor y ve a Configuración (icono de engranaje en la esquina superior derecha)
2. Haz clic en "MCP" en la barra lateral izquierda
3. Haz clic en "Add new global MCP server"
4. Introduce los siguientes detalles:

Modo predeterminado

{
  "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. Prefiere configurarlo aquí en lugar de pasarlo en los parámetros de las herramientas.
• BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION: Opcional. Configúralo en "true" para que todas las herramientas de transferencia/pago se ejecuten inmediatamente (sin paso de vista previa). El valor predeterminado "false" utiliza el flujo de vista previa y confirmación.

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"
      }
    }
  }
}

Integración con Claude Desktop

Para conectarte al servidor MCP desde Claude Desktop:

1. Abre Claude Desktop y ve a Configuración
2. Haz clic en "Developer" en la barra lateral izquierda
3. Haz clic en el botón "Edit Config"
4. Añade la siguiente configuración al archivo 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 ejecutar transferencias inmediatamente sin vista previa/confirmación.

5. Guarda el archivo y reinicia Claude Desktop

Una vez conectado, puedes usar todas las indicaciones y herramientas de MCP directamente en tus conversaciones de Claude Desktop. Por ejemplo:

• "Analiza esta dirección: 0x123..."
• "Explica el concepto EVM de gas"
• "Consulta el último bloque en BSC"

Integración con otros clientes

Si deseas integrar BNBChain MCP en tu propio cliente, consulta el directorio de ejemplos para obtener información más detallada e implementaciones de referencia.

Los ejemplos demuestran:

• Cómo configurar el cliente MCP
• Autenticación y configuración
• Realizar llamadas API para interactuar con redes blockchain
• Manejo de respuestas y errores
• Mejores prácticas para la integración

Desarrollo local

Requisitos previos

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

Inicio rápido

1. Clona el repositorio:

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

2. Configura las variables de entorno:

cp .env.example .env

Edita el archivo .env con tu configuración:

• PRIVATE_KEY: Tu clave privada de cartera (requerida para operaciones de transacción)
• LOG_LEVEL: Configura el nivel de registro (DEBUG, INFO, WARN, ERROR)
• PORT: Número de puerto del servidor (predeterminado: 3001)

3. Instala las dependencias e inicia el servidor de desarrollo:

# Install project dependencies
bun install

# Start the development server
bun dev:sse

Pruebas con clientes MCP

Configura el servidor local en tus clientes MCP usando esta plantilla:

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

Pruebas con interfaz web

Usamos @modelcontextprotocol/inspector para pruebas. Inicia la interfaz de prueba:

bun run test

Scripts disponibles

• bun dev:sse: Inicia el servidor de desarrollo con recarga automática
• bun build: Compila el proyecto
• bun test: Ejecuta el conjunto de pruebas

Indicaciones y herramientas disponibles

Indicaciones

Nombre	Descripción
analyze_block	Analiza un bloque y proporciona información detallada sobre su contenido
analyze_transaction	Analiza una transacción específica
analyze_address	Analiza una dirección EVM
interact_with_contract	Obtén orientación sobre cómo interactuar con un contrato inteligente
explain_evm_concept	Obtén una explicación de un concepto EVM
compare_networks	Compara diferentes redes compatibles con EVM
analyze_token	Analiza un token ERC20 o NFT
how_to_register_mcp_as_erc8004_agent	Obtén orientación sobre cómo registrar un servidor MCP como agente ERC-8004

Herramientas

Nombre	Descripción
get_block_by_hash	Obtén un bloque por hash
get_block_by_number	Obtén un bloque por número
get_latest_block	Obtén el último bloque
get_transaction	Obtén información detallada sobre una transacción específica por su hash
get_transaction_receipt	Obtén un recibo de transacción por su hash
estimate_gas	Estima el costo de gas para una transacción
transfer_native_token	Transfiere tokens nativos (BNB, ETH, MATIC, etc.) a una dirección
approve_token_spending	Aprueba que otra dirección gaste tus tokens ERC20
transfer_nft	Transfiere un NFT (token ERC721) de una dirección a otra
transfer_erc1155	Transfiere tokens ERC1155 a otra dirección
transfer_erc20	Transfiere tokens ERC20 a una dirección
get_address_from_private_key	Obtén la dirección EVM derivada de una clave privada
get_chain_info	Obtén información de la cadena para una red específica
get_supported_networks	Obtén la lista de redes compatibles
resolve_ens	Resuelve un nombre ENS a una dirección EVM
is_contract	Comprueba si una dirección es un contrato inteligente o una cuenta de propiedad externa (EOA)
read_contract	Lee datos de un contrato inteligente llamando a una función view/pure
write_contract	Escribe datos en un contrato inteligente llamando a una función que cambia el estado
get_erc20_token_info	Obtén información del token ERC20
get_native_balance	Obtén el saldo de tokens nativos para una dirección
get_erc20_balance	Obtén el saldo de tokens ERC20 para una dirección
get_nft_info	Obtén información detallada sobre un NFT específico
check_nft_ownership	Comprueba si una dirección posee un NFT específico
get_erc1155_token_metadata	Obtén los metadatos de un token ERC1155
get_nft_balance	Obtén el número total de NFT que posee una dirección de una colección específica
get_erc1155_balance	Obtén el saldo de un ID de token ERC1155 específico que posee una dirección

Herramientas de agente ERC-8004

Registra y resuelve agentes de IA en el Registro de Identidad ERC-8004 (Trustless Agents). Redes compatibles: BSC (56), BSC Testnet (97), Ethereum, Base, Polygon y sus testnets donde está desplegado el registro oficial. El agentURI debe apuntar a un archivo de metadatos JSON que siga el Perfil de Metadatos de Agente (nombre, descripción, imagen y services como el endpoint MCP).

Nombre	Descripción
register_erc8004_agent	Registra un agente en el Registro de Identidad ERC-8004; devuelve el ID del agente
set_erc8004_agent_uri	Actualiza el URI de metadatos de un agente ERC-8004 existente (solo propietario)
get_erc8004_agent	Obtén información del agente (propietario y tokenURI) del Registro de Identidad
get_erc8004_agent_wallet	Obtén la cartera de pago verificada de un agente (para x402 / pagos)

Herramientas de Greenfield

Nombre	Descripción
gnfd_get_bucket_info	Obtener información detallada sobre un bucket específico
gnfd_list_buckets	Listar todos los buckets propiedad de una dirección
gnfd_create_bucket	Crear un nuevo bucket
gnfd_delete_bucket	Eliminar un bucket
gnfd_get_object_info	Obtener información detallada sobre un objeto específico
gnfd_list_objects	Listar todos los objetos en un bucket
gnfd_upload_object	Subir un objeto a un bucket
gnfd_download_object	Descargar un objeto de un bucket
gnfd_delete_object	Eliminar un objeto de un bucket
gnfd_create_folder	Crear una carpeta en un bucket
gnfd_get_account_balance	Obtener el saldo de una cuenta
gnfd_deposit_to_payment	Depositar fondos en una cuenta de pago
gnfd_withdraw_from_payment	Retirar fondos de una cuenta de pago
gnfd_disable_refund	Deshabilitar reembolsos para una cuenta de pago (IRREVERSIBLE)
gnfd_get_payment_accounts	Listar todas las cuentas de pago propiedad de una dirección
gnfd_get_payment_account_info	Obtener información detallada sobre una cuenta de pago
gnfd_create_payment	Crear una nueva cuenta de pago
gnfd_get_payment_balance	Obtener el saldo de la cuenta de pago

Redes Compatibles

Compatible con BSC, opBNB, Greenfield, Ethereum y otras redes principales compatibles con EVM. Para más detalles, consulta src/evm/chains.ts.

Registro de agentes ERC-8004 está disponible en cadenas donde está desplegado el registro oficial: BSC (56), BSC Testnet (97), Ethereum (1), Sepolia (11155111), Base (8453), Base Sepolia (84532), Polygon (137), Polygon Amoy (80002), Arbitrum (42161), Arbitrum Sepolia (421614). La clave privada se utiliza únicamente para firmar la transacción de registro o actualización y no se almacena ni se registra.

Contribuciones

¡Damos la bienvenida a contribuciones a BNBChain MCP! Así es como puedes ayudar:

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad
3. Realiza tus cambios
4. Sube tu rama
5. Crea una Pull Request

Asegúrate de que tu código siga nuestros estándares de codificación e incluya pruebas adecuadas.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Referencias y Agradecimientos

Este proyecto se basa e inspira en los siguientes proyectos de código abierto:

• TermiX-official/bsc-mcp - Implementación original de BSC MCP
• mcpdotdirect/evm-mcp-server - Implementación de servidor MCP compatible con EVM

Extendemos nuestro agradecimiento a los autores originales por sus contribuciones al ecosistema blockchain.