Apache 2.0
BNBChain MCP is a toolkit for interacting with BNB Chain and other EVM-compatible networks through AI-powered interfaces:
Query blockchain data: Retrieve blocks, transactions, and chain information by hash, number, or latest state
Smart contract interactions: Read from view/pure functions, execute state-changing transactions, and estimate gas costs
Wallet operations: Derive addresses from private keys, check balances, and transfer native tokens
Token management: Handle ERC20, ERC721 (NFTs), and ERC1155 tokens, including transfers, approvals, and metadata queries
Address analysis: Check if addresses are contracts or EOAs (externally owned accounts)
ENS resolution: Convert ENS names to EVM addresses
Network management: Query supported networks and their details
Greenfield network support: Manage files (buckets, objects, folders) and payment accounts
Security: Private keys are used only for signing transactions and not stored
Provides tools for interacting with BNB Chain through natural language, including blockchain queries, smart contract interaction, wallet management, token operations, and NFT management.
Supports local development with Bun, providing setup instructions and development scripts for running and testing the MCP server.
Supports interaction with Ethereum and other EVM-compatible networks, enabling blockchain development, smart contract interaction, and network management through AI-powered interfaces.
Supports local development with Node.js, listed as a prerequisite for running the MCP server locally.
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.)
Integration with Cursor
To connect to the MCP server from Cursor:
Open Cursor and go to Settings (gear icon in the top right)
Click on "MCP" in the left sidebar
Click "Add new global MCP server"
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)"
}
}
}
}
SSE mode
{
"mcpServers": {
"bnbchain-mcp": {
"command": "npx",
"args": ["-y", "@bnb-chain/mcp@latest", "--sse"],
"env": {
"PRIVATE_KEY": "your_private_key_here. (optional)"
}
}
}
}
Integration with Claude Desktop
To connect to the MCP server from Claude Desktop:
Open Claude Desktop and go to Settings
Click on "Developer" in the left sidebar
Click the "Edit Config" Button
Add the following configuration to the
claude_desktop_config.jsonfile:
{
"mcpServers": {
"bnbchain-mcp": {
"command": "npx",
"args": ["-y", "@bnb-chain/mcp@latest"],
"env": {
"PRIVATE_KEY": "your_private_key_here"
}
}
}
}
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
Quick Start
Clone the repository:
git clone https://github.com/bnb-chain/bnbchain-mcp.git
cd bnbchain-mcp
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)
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 reloadbun build: Build the projectbun test: Run test suite
Available Prompts and Tools
Prompts
Name | Description |
analyze_block | Analyze a block and provide detailed information about its contents |
analyze_transaction | Analyze a specific transaction |
analyze_address | Analyze an EVM address |
interact_with_contract | Get guidance on interacting with a smart contract |
explain_evm_concept | Get an explanation of an EVM concept |
compare_networks | Compare different EVM-compatible networks |
analyze_token | Analyze an ERC20 or NFT token |
Tools
Name | Description |
get_block_by_hash | Get a block by hash |
get_block_by_number | Get a block by number |
get_latest_block | Get the latest block |
get_transaction | Get detailed information about a specific transaction by its hash |
get_transaction_receipt | Get a transaction receipt by its hash |
estimate_gas | Estimate the gas cost for a transaction |
transfer_native_token | Transfer native tokens (BNB, ETH, MATIC, etc.) to an address |
approve_token_spending | Approve another address to spend your ERC20 tokens |
transfer_nft | Transfer an NFT (ERC721 token) from one address to another |
transfer_erc1155 | Transfer ERC1155 tokens to another address |
transfer_erc20 | Transfer ERC20 tokens to an address |
get_address_from_private_key | Get the EVM address derived from a private key |
get_chain_info | Get chain information for a specific network |
get_supported_networks | Get list of supported networks |
resolve_ens | Resolve an ENS name to an EVM address |
is_contract | Check if an address is a smart contract or an externally owned account (EOA) |
read_contract | Read data from a smart contract by calling a view/pure function |
write_contract | Write data to a smart contract by calling a state-changing function |
get_erc20_token_info | Get ERC20 token information |
get_native_balance | Get native token balance for an address |
get_erc20_balance | Get ERC20 token balance for an address |
get_nft_info | Get detailed information about a specific NFT |
check_nft_ownership | Check if an address owns a specific NFT |
get_erc1155_token_metadata | Get the metadata for an ERC1155 token |
get_nft_balance | Get the total number of NFTs owned by an address from a specific collection |
get_erc1155_balance | Get the balance of a specific ERC1155 token ID owned by an address |
Greenfield tools
Name | Description |
gnfd_get_bucket_info | Get detailed information about a specific bucket |
gnfd_list_buckets | List all buckets owned by an address |
gnfd_create_bucket | Create a new bucket |
gnfd_delete_bucket | Delete a bucket |
gnfd_get_object_info | Get detailed information about a specific object |
gnfd_list_objects | List all objects in a bucket |
gnfd_upload_object | Upload an object to a bucket |
gnfd_download_object | Download an object from a bucket |
gnfd_delete_object | Delete an object from a bucket |
gnfd_create_folder | Create a folder in a bucket |
gnfd_get_account_balance | Get the balance for an account |
gnfd_deposit_to_payment | Deposit funds into a payment account |
gnfd_withdraw_from_payment | Withdraw funds from a payment account |
gnfd_disable_refund | Disable refund for a payment account (IRREVERSIBLE) |
gnfd_get_payment_accounts | List all payment accounts owned by an address |
gnfd_get_payment_account_info | Get detailed information about a payment account |
gnfd_create_payment | Create a new payment account |
gnfd_get_payment_balance | Get payment account balance |
Supported Networks
Supports BSC, opBNB, Greenfield, Ethereum, and other major EVM-compatible networks. For more details, see src/evm/chains.ts.
Contributing
We welcome contributions to BNBChain MCP! Here's how you can help:
Fork the repository
Create a feature branch
Commit your changes
Push to your branch
Create a Pull Request
Please ensure your code follows our coding standards and includes appropriate tests.
License
This project is licensed under the MIT License - see the LICENSE file for details.
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.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
bnbchain-mcp
- Description
- Core Modules
- Integration with Cursor
- Integration with Claude Desktop
- Integration with Other Clients
- Local Development
- Available Prompts and Tools
- Supported Networks
- Contributing
- License
- References and Acknowledgments
Related Resources
Related MCP Servers
- MIT License
- MIT License
- MIT License