BNBChain MCP

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
• DappBay: Read-only access to DappBay, the official BNB Chain dApp registry: check whether a website belongs to a listed dApp, look up official profiles, search and rank dApps

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

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
how_to_register_mcp_as_erc8004_agent	Get guidance on registering an MCP server as an ERC-8004 agent

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

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).

Name	Description
register_erc8004_agent	Register an agent on the ERC-8004 Identity Registry; returns agent ID
set_erc8004_agent_uri	Update the metadata URI for an existing ERC-8004 agent (owner only)
get_erc8004_agent	Get agent info (owner and tokenURI) from the Identity Registry
get_erc8004_agent_wallet	Get the verified payment wallet for an agent (for x402 / payments)

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

DappBay tools

Read-only tools backed by DappBay, the official dApp registry maintained by BNB Chain. No API key or private key is needed. Every successful response carries meta.source and meta.coverage: listed dApps and websites are verified by DappBay, but the registry is not exhaustive, so "not listed" never means "unofficial" or "unsafe". Contract addresses are not exposed.

Name	Description
resolve_dapp	Check whether a website belongs to a listed dApp (listed, red_alarm, not_in_listed_records, not_listed)
get_dapp	Get a dApp's official profile: website, socials, category, chains, Red Alarm status and weekly metrics
search_dapps	Search listed dApps by name or slug keyword, category or chain
top_dapps	Rank dApps by users, TVL or transactions over a daily, weekly or monthly window

resolve_dapp statuses:

• listed: the domain matches a listed dApp. A warning is added when the dApp is inactive, because its domain may have changed owner.
• red_alarm: the domain matches a dApp flagged by BNB Chain Red Alarm; red_alarm.reason explains why.
• not_in_listed_records: the domain is not listed but looks similar to the dApps in similar_listed. It may be a phishing site or a domain DappBay has not recorded yet.
• not_listed: no record. This is not a judgment either way.

Red Alarm fields: risk_level is the lowercase stored level (no_risk, some, unknown, low, medium, high, or null); reason is the human-readable explanation; marked_at is when it was flagged. For example, RISK_LEVEL_MEDIUM becomes medium. These values preserve the stored enum, not the website display-label mapping.

Freshness fields: profile_updated_at is when the dApp listing was last edited; metrics_as_of is the date of the users/TVL/transactions statistics.

Inputs and pagination:

• resolve_dapp: url is required, trimmed, 1-2048 characters. Use HTTP/HTTPS or a bare domain; other schemes and contract addresses are rejected by the API.
• get_dapp: idOrUniqName is a required string of 1-255 characters. Numeric strings are IDs; other strings are slugs. A missing record returns data: null and meta.empty: true.
• search_dapps: optional q (trimmed, up to 100 characters; matches name or slug), category, chain, page (1-50, default 1), and pageSize (1-20, default 10). meta.pagination contains page, page_size, total_count, and has_more; continue only while has_more is true. Archives are excluded before pagination. An out-of-range result page is distinguished from an unlisted project.
• top_dapps: required metric (users, tvl, txns); optional granularity (daily, weekly, monthly, default weekly), category, chain, and pageSize (1-20, default 10). Values, metrics.chain, and metrics_as_of come from the same selected statistics row, including when no chain filter is provided; values are not a cross-chain sum.
• Categories use the same canonical values for inputs and outputs: DeFi, Games, NFTs, Social, AI, DePIN, Infra-and-Tools, RWA, Other (unrecognized stored categories are returned as null). Chain filters are bsc, opbnb, greenfield.

Successful results are JSON text containing { data, meta }. Schema validation failures use the MCP -32602 protocol error; upstream HTTP/network failures return isError: true with readable text. The 8-second HTTP deadline covers the response body as well as headers. The response-level meta.metrics_as_of is the newest timestamp among returned items; use each item's timestamp for its own metrics.

Set DAPPBAY_API_BASE to point the tools at another DappBay API (defaults to https://dappbay.bnbchain.org/api/v1).

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.

Publishing

Run the Release and Publish GitHub Actions workflow manually on main. Semantic-release determines the next version from commit messages, then publishes the npm package and GitHub release.

The @bnb-chain/mcp package must have an npm trusted publisher configured for GitHub Actions: organization bnb-chain, repository bnbchain-mcp, workflow filename release.yml, no environment name, and direct npm publish allowed. The workflow uses OIDC with id-token: write; no NPM_TOKEN is required. Keep package.json's repository.url aligned with this repository. See the npm trusted publishing documentation.

Contributing

We welcome contributions to BNBChain MCP! Here's how you can help:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. 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.