Interact with BNBChain and EVM Networks

BNBChain MCP (Model Context Protocol)

A powerful toolkit for interacting with BNB Chain and other EVM-compatible networks through natural language processing and AI assistance.

Description

BNBChain MCP is a Model Context Protocol implementation that enables seamless interaction with blockchain networks through AI-powered interfaces. It provides a comprehensive set of tools and resources for blockchain development, smart contract interaction, and network management.

Core Modules

The project is organized into several core modules:

• Blocks: Query and manage blockchain blocks
• Contracts: Interact with smart contracts
• Network: Network information and management
• NFT: NFT (ERC721/ERC1155) operations
• Tokens: Token (ERC20) operations
• Transactions: Transaction management
• Wallet: Wallet operations and management
• Common: Shared utilities and types
• Greenfield: Support file management operations on Greenfield network including, uploading, downloading, and managing files and buckets
• Additional features coming soon (Greenfield, Swap, Bridge, etc.)
• Agents (ERC-8004): Register and resolve on-chain AI agent identities (ERC-8004 Trustless Agents) on BSC and BSC Testnet

Important Notes

We do not recommend deploying this MCP Server on the public internet. (1) The SSE endpoint has no authentication-anyone who can reach it can use the server. (2) There is no centralized service that custodies private keys or funds; keys and signing are the responsibility of the client. If you still need to deploy it publicly, add an authentication layer in front (e.g. API keys, JWT, or a reverse proxy with auth), or deploy a keyless version that only exposes read-only or non-sensitive tools.

Credentials: Prefer setting PRIVATE_KEY in the MCP server environment. Do not pass the private key in tool parameters when avoidable, as it may be stored in conversation history, client logs, or request logs and lead to exposure.

Transfer and payment confirmation

Transfer and payment tools (e.g. transfer_native_token, transfer_erc20, approve_token_spending, transfer_nft, transfer_erc1155, gnfd_deposit_to_payment, gnfd_withdraw_from_payment, gnfd_create_payment_account) use a preview-then-confirm flow by default so that no funds move until the user explicitly confirms.

• Default behavior: Calling a transfer or payment tool returns a preview (recipient, amount, network, etc.) and a short-lived confirmToken. No transaction is sent. To execute, call the confirm_transfer tool with that confirmToken and your privateKey. The token expires after 5 minutes.
• Skipping confirmation (per call): Pass skipConfirmation: true in the tool arguments when the caller has already confirmed or when running in an automated script. The tool will then execute immediately and return the transaction result.
• Skipping confirmation (server-wide): Set the environment variable BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true so that all transfer/payment tools execute immediately without returning a preview. Use this for headless or scripted environments where you do not need a confirmation step.

Example flow with confirmation:

1. Call transfer_native_token with toAddress, amount, network (and optionally privateKey). Do not set skipConfirmation.
2. The server returns { preview: { toAddress, amount, network }, confirmToken: "...", message: "..." }.
3. Review the preview, then call confirm_transfer with confirmToken and privateKey to execute the transfer.

Integration with Cursor

To connect to the MCP server from Cursor:

1. Open Cursor and go to Settings (gear icon in the top right)
2. Click on "MCP" in the left sidebar
3. Click "Add new global MCP server"
4. Enter the following details:

Default mode

{
  "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: Optional. Prefer setting here instead of passing in tool parameters.
• BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION: Optional. Set to "true" to make all transfer/payment tools execute immediately (no preview step). Default "false" uses the preview-then-confirm flow.

SSE mode

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

Integration with Claude Desktop

To connect to the MCP server from Claude Desktop:

1. Open Claude Desktop and go to Settings
2. Click on "Developer" in the left sidebar
3. Click the "Edit Config" Button
4. Add the following configuration to the claude_desktop_config.json file:

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

Optional env: BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION=true to execute transfers immediately without preview/confirm.

5. Save the file and restart Claude Desktop

Once connected, you can use all the MCP prompts and tools directly in your Claude Desktop conversations. For example:

• "Analyze this address: 0x123..."
• "Explain the EVM concept of gas"
• "Check the latest block on BSC"

Integration with Other Clients

If you want to integrate BNBChain MCP into your own client, please check out the examples directory for more detailed information and reference implementations.

The examples demonstrate:

• How to set up the MCP client
• Authentication and configuration
• Making API calls to interact with blockchain networks
• Handling responses and errors
• Best practices for integration

Local Development

Prerequisites

• bun v1.2.10 or higher
• Node.js v17 or higher

Quick Start

1. Clone the repository:

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

2. Set up environment variables:

cp .env.example .env

Edit .env file with your configuration:

• PRIVATE_KEY: Your wallet private key (required for transaction operations)
• LOG_LEVEL: Set logging level (DEBUG, INFO, WARN, ERROR)
• PORT: Server port number (default: 3001)

3. Install dependencies and start development server:

# Install project dependencies
bun install

# Start the development server
bun dev:sse

Testing with MCP Clients

Configure the local server in your MCP clients using this template:

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

Testing with Web UI

We use @modelcontextprotocol/inspector for testing. Launch the test UI:

bun run test

Available Scripts

• bun dev:sse: Start development server with hot reload
• bun build: Build the project
• bun test: Run test suite

Available Prompts and Tools

Prompts

Tools

ERC-8004 Agent tools

Register and resolve AI agents on the ERC-8004 Identity Registry (Trustless Agents). Supported networks: BSC (56), BSC Testnet (97), Ethereum, Base, Polygon, and their testnets where the official registry is deployed. The agentURI should point to a JSON metadata file following the Agent Metadata Profile (name, description, image, and services such as MCP endpoint).

Greenfield tools

Supported Networks

Supports BSC, opBNB, Greenfield, Ethereum, and other major EVM-compatible networks. For more details, see src/evm/chains.ts.

ERC-8004 agent registration is available on chains where the official registry is deployed: BSC (56), BSC Testnet (97), Ethereum (1), Sepolia (11155111), Base (8453), Base Sepolia (84532), Polygon (137), Polygon Amoy (80002), Arbitrum (42161), Arbitrum Sepolia (421614). Private key is used only to sign the registration or update transaction and is not stored or logged.

References and Acknowledgments

This project is built upon and inspired by the following open-source projects:

• TermiX-official/bsc-mcp - Original BSC MCP implementation
• mcpdotdirect/evm-mcp-server - EVM-compatible MCP server implementation

We extend our gratitude to the original authors for their contributions to the blockchain ecosystem.