BNBChain MCP (Model Context Protocol)

BNBChain MCP（Model Context Protocol）

通过自然语言处理和 AI 助手，轻松与 BNB Chain 及其他兼容 EVM 的网络交互的强大工具包。

描述

BNBChain MCP 是 Model Context Protocol 的一种实现，可通过 AI 驱动的接口与区块链网络无缝交互。它提供全面的工具和资源，支持区块链开发、智能合约交互和网络管理。

核心模块

项目由以下几个核心模块组成：

• 区块：查询和管理区块链区块
• 合约：与智能合约交互
• 网络：网络信息和管理
• NFT：NFT（ERC721/ERC1155）操作
• 代币：代币（ERC20）操作
• 交易：交易管理
• 钱包：钱包操作和管理
• 通用：共享实用工具和类型
• Greenfield：支持 Greenfield 网络上的文件管理操作，包括上传、下载以及管理文件和存储桶
• 即将推出更多功能（Greenfield、Swap、Bridge 等）
• Agent（ERC-8004）：在 BSC 和 BSC Testnet 上注册和解析链上 AI Agent 身份（ERC-8004 Trustless Agents）

重要说明

我们不建议将此 MCP 服务部署到公共互联网。（1）SSE 端点没有身份验证——任何能够访问它的人都可以使用此服务。（2）没有集中式服务托管私钥或资金；密钥和签名由客户端负责。如果仍需将其公开部署，请在前面添加身份验证层（例如 API 密钥、JWT 或带身份验证的反向代理），或部署仅公开只读或非敏感工具的无密钥版本。

**凭据：**建议在 MCP 服务环境中设置 PRIVATE_KEY。尽可能不要在工具参数中传递私钥，因为它可能会被存储在对话历史记录、客户端日志或请求日志中，从而导致泄露。

转账和付款确认

转账和付款工具（例如 transfer_native_token、transfer_erc20、approve_token_spending、transfer_nft、transfer_erc1155、gnfd_deposit_to_payment、gnfd_withdraw_from_payment、gnfd_create_payment_account）默认采用先预览、后确认的流程，因此只有用户明确确认后才会转移资金。

• 默认行为：调用转账或付款工具会返回一个预览（收款方、金额、网络等）和一个短时有效的 confirmToken。不会发送交易。要执行操作，请使用该 confirmToken 和你的 privateKey 调用 confirm_transfer 工具。令牌将在 5 分钟后过期。
• **跳过确认（单次调用）：**当调用方已经确认，或在自动化脚本中运行时，可在工具参数中传入 skipConfirmation: true。此时工具将立即执行并返回交易结果。
• **跳过确认（整个服务）：**设置环境变量 BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true，使所有转账/付款工具立即执行，而不返回预览。在无需确认步骤的无头环境或脚本环境中使用此选项。

确认流程示例：

1. 使用 toAddress、amount、network（以及可选的 privateKey）调用 transfer_native_token。不要设置 skipConfirmation。
2. 服务返回 { preview: { toAddress, amount, network }, confirmToken: "...", message: "..." }。
3. 检查预览，然后使用 confirmToken 和 privateKey 调用 confirm_transfer，以执行转账。

与 Cursor 集成

要从 Cursor 连接到 MCP 服务：

1. 打开 Cursor，然后前往 Settings（右上角的齿轮图标）
2. 点击左侧边栏中的“MCP”
3. 点击“Add new global MCP server”
4. 输入以下详细信息：

默认模式

{
  "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：可选。建议在此处设置，而不是通过工具参数传入。
• BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION：可选。设置为 "true"，即可让所有转账/付款工具立即执行（跳过预览步骤）。默认值 "false" 会使用先预览、再确认的流程。

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

与 Claude Desktop 集成

要从 Claude Desktop 连接到 MCP 服务：

1. 打开 Claude Desktop，然后前往 Settings
2. 点击左侧边栏中的“Developer”
3. 点击“Edit Config”按钮
4. 将以下配置添加到 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"
      }
    }
  }
}

可选环境变量：BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true，可在不预览/确认的情况下立即执行转账。

5. 保存文件并重启 Claude Desktop

连接后，你可以直接在 Claude Desktop 对话中使用所有 MCP 提示词和工具。例如：

• “分析此地址：0x123...”
• “解释 EVM 中 gas 的概念”
• “查看 BSC 上的最新区块”

与其他客户端集成

如果你想将 BNBChain MCP 集成到自己的客户端中，请查看 examples 目录，获取更详细的信息和参考实现。

这些示例演示了：

• 如何设置 MCP 客户端
• 身份验证和配置
• 如何发起 API 调用，与区块链网络交互
• 如何处理响应和错误
• 集成最佳实践

本地开发

先决条件

• bun v1.2.10 或更高版本
• Node.js v17 或更高版本

快速开始

1. 克隆代码库：

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

2. 设置环境变量：

cp .env.example .env

编辑 .env 文件并填写配置：

• PRIVATE_KEY：你的钱包私钥（交易操作必需）
• LOG_LEVEL：设置日志级别（DEBUG、INFO、WARN、ERROR）
• PORT：服务端口号（默认值：3001）

3. 安装依赖并启动开发服务器：

# Install project dependencies
bun install

# Start the development server
bun dev:sse

使用 MCP 客户端测试

使用此模板在 MCP 客户端中配置本地服务：

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

使用 Web UI 测试

我们使用 @modelcontextprotocol/inspector 进行测试。启动测试 UI：

bun run test

可用脚本

• bun dev:sse：启动支持热重载的开发服务器
• bun build：构建项目
• bun test：运行测试套件

可用提示词和工具

提示词

名称	描述
analyze_block	分析区块并详细介绍其内容
analyze_transaction	分析特定交易
analyze_address	分析 EVM 地址
interact_with_contract	获取与智能合约交互的指导
explain_evm_concept	获取 EVM 概念的解释
compare_networks	比较不同的 EVM 兼容网络
analyze_token	分析 ERC20 或 NFT 代币
how_to_register_mcp_as_erc8004_agent	获取将 MCP 服务注册为 ERC-8004 Agent 的指导

工具

名称	描述
get_block_by_hash	根据哈希获取区块
get_block_by_number	根据区块号获取区块
get_latest_block	获取最新区块
get_transaction	根据哈希获取特定交易的详细信息
get_transaction_receipt	根据哈希获取交易回执
estimate_gas	估算交易的 Gas 费用
transfer_native_token	向某个地址转移原生代币（BNB、ETH、MATIC 等）
approve_token_spending	授权另一个地址支用你的 ERC20 代币
transfer_nft	将 NFT（ERC721 代币）从一个地址转移到另一个地址
transfer_erc1155	向另一个地址转移 ERC1155 代币
transfer_erc20	向某个地址转移 ERC20 代币
get_address_from_private_key	获取由私钥推导出的 EVM 地址
get_chain_info	获取特定网络的链信息
get_supported_networks	获取支持的网络列表
resolve_ens	将 ENS 名称解析为 EVM 地址
is_contract	检查某个地址是智能合约还是外部拥有账户（EOA）
read_contract	通过调用 view/pure 函数读取智能合约数据
write_contract	通过调用更改状态的函数向智能合约写入数据
get_erc20_token_info	获取 ERC20 代币信息
get_native_balance	获取某个地址的原生代币余额
get_erc20_balance	获取某个地址的 ERC20 代币余额
get_nft_info	获取特定 NFT 的详细信息
check_nft_ownership	检查某个地址是否拥有特定 NFT
get_erc1155_token_metadata	获取 ERC1155 代币的元数据
get_nft_balance	获取某个地址在特定集合中拥有的 NFT 总数
get_erc1155_balance	获取某个地址拥有的特定 ERC1155 代币 ID 的余额

ERC-8004 Agent 工具

在 ERC-8004 身份注册表（Trustless Agents）中注册和解析 AI Agent。支持的网络：BSC（56）、BSC Testnet（97）、Ethereum、Base、Polygon，以及部署了官方注册表的相应测试网。agentURI 应指向符合 Agent Metadata Profile 的 JSON 元数据文件（包括名称、描述、图像和 services，例如 MCP 端点）。

名称	描述
register_erc8004_agent	在 ERC-8004 身份注册表中注册 Agent；返回 Agent ID
set_erc8004_agent_uri	更新现有 ERC-8004 Agent 的元数据 URI（仅限所有者）
get_erc8004_agent	从身份注册表获取 Agent 信息（所有者和 tokenURI）
get_erc8004_agent_wallet	获取 Agent 的已验证付款钱包（用于 x402 / 付款）

Greenfield 工具

名称	描述
gnfd_get_bucket_info	获取指定存储桶的详细信息
gnfd_list_buckets	列出某个地址拥有的所有存储桶
gnfd_create_bucket	创建新存储桶
gnfd_delete_bucket	删除存储桶
gnfd_get_object_info	获取指定对象的详细信息
gnfd_list_objects	列出存储桶中的所有对象
gnfd_upload_object	将对象上传到存储桶
gnfd_download_object	从存储桶下载对象
gnfd_delete_object	从存储桶删除对象
gnfd_create_folder	在存储桶中创建文件夹
gnfd_get_account_balance	获取账户余额
gnfd_deposit_to_payment	向付款账户存入资金
gnfd_withdraw_from_payment	从付款账户提取资金
gnfd_disable_refund	禁用付款账户退款（不可逆）
gnfd_get_payment_accounts	列出某个地址拥有的所有付款账户
gnfd_get_payment_account_info	获取付款账户的详细信息
gnfd_create_payment	创建新的付款账户
gnfd_get_payment_balance	获取付款账户余额

支持的网络

支持 BSC、opBNB、Greenfield、Ethereum 和其他主要的 EVM 兼容网络。有关更多详情，请参阅 src/evm/chains.ts。

ERC-8004 Agent 注册适用于部署了官方注册表的链：BSC（56）、BSC Testnet（97）、Ethereum（1）、Sepolia（11155111）、Base（8453）、Base Sepolia（84532）、Polygon（137）、Polygon Amoy（80002）、Arbitrum（42161）、Arbitrum Sepolia（421614）。私钥仅用于签署注册或更新交易，不会被存储或记录。

贡献

欢迎为 BNBChain MCP 贡献！以下是参与方式：

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 推送到你的分支
5. 创建 Pull Request

请确保代码遵循我们的编码规范，并包含适当的测试。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

参考与致谢

本项目基于以下开源项目构建，并从中汲取灵感：

• TermiX-official/bsc-mcp - BSC MCP 的原始实现
• mcpdotdirect/evm-mcp-server - 兼容 EVM 的 MCP 服务实现

我们谨向原作者致以诚挚谢意，感谢他们为区块链生态系统所作的贡献。