bnb-chain/bnbchain-skills/bnbchain-mcp-skill

BNB Chain MCP Skill

How to connect to the BNB Chain MCP server and use its tools: blocks, transactions, contracts, tokens, NFTs, wallet, ERC-8004 agents, and Greenfield. Use this skill when working with BNB Chain / opBNB / EVM or Greenfield via MCP.

Connection and credentials

• Run the server: npx @bnb-chain/mcp@latest (fetches from npm at runtime). Source: github.com/bnb-chain/bnbchain-mcp.
• RPC: Default chains use built-in RPC; no config unless self-hosting or custom RPC.
• PRIVATE_KEY: Omit or leave empty for read-only (blocks, balances, contract reads). Set in the MCP server env for state-changing tools (transfers, write_contract, approve_token_spending, ERC-8004 register/set_uri, Greenfield writes). Never log or expose private keys.
• Read-only vs state-changing: Block/balance/contract-read tools work without a key; transfers and writes require PRIVATE_KEY in the server environment.

1. MCP server config

Add the bnbchain-mcp server to the MCP client config (e.g. Cursor MCP settings, Claude Desktop claude_desktop_config.json).

Default (stdio):

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

SSE mode: "args": ["-y", "@bnb-chain/mcp@latest", "--sse"] (and client SSE URL if required). Local dev server (e.g. bun dev:sse in bnbchain-mcp): "url": "http://localhost:3001/sse" with the same env.

Restart or reload the MCP client after changing config so the server starts.

2. Credentials and environment

• RPC: Built-in for default chains.
• PRIVATE_KEY: Set in the server’s env when state-changing tools are needed; leave empty for read-only. Do not commit or echo keys.

3. Agent registration (ERC-8004)

1. Register the agent on-chain with the MCP tool `register_erc8004_agent` (see references/erc8004-tools-reference.md).
2. Owners can then check registration on 8004scan (mainnet) or 8004scan (testnet).

4. Quick reference — tools and prompts

Network parameter

• Read-only tools (blocks, balances, contract reads, get_chain_info, etc.): `network` is optional; default is bsc. Use `get_supported_networks` to list options.
• Write operations (transfer_native_token, transfer_erc20, transfer_nft, transfer_erc1155, approve_token_spending, write_contract, register_erc8004_agent, set_erc8004_agent_uri, Greenfield writes): `network` is REQUIRED. There is no default for writes. If the user does not specify the network, you MUST ask before calling the tool. Do not assume or default to mainnet (bsc); accidental mainnet execution causes irreversible financial loss.

Tool categories

Prompts (MCP prompts)

Use the MCP prompt names when the user wants analysis or guidance:

• analyze_block — Analyze a block and its contents
• analyze_transaction — Analyze a specific transaction
• analyze_address — Analyze an EVM address
• interact_with_contract — Guidance on interacting with a smart contract
• explain_evm_concept — Explain an EVM concept
• compare_networks — Compare EVM-compatible networks
• analyze_token — Analyze an ERC20 or NFT token
• how_to_register_mcp_as_erc8004_agent — Guidance on registering MCP as ERC-8004 agent

5. Reference files (per-tool usage)

For parameter names, examples, and detailed usage of each tool, use:

6. Safety and best practices

1. Confirm before sending transactions: For transfer_*, write_contract, or approve_token_spending, confirm recipient, amount, and network before calling the tool.
2. Network required for writes: For any write (transfers, write_contract, approve_token_spending, ERC-8004 register/set_uri), you MUST have an explicit network from the user. If not specified, ask — do not default to mainnet. Do not use advisory language like "prefer testnet" as a substitute; the constraint is: no network specified → do not call the write tool until the user confirms.
3. Private keys: Only in MCP server env; never in chat or logs.
4. ERC-8004 agentURI: JSON metadata per the Agent Metadata Profile (name, description, image, services e.g. MCP endpoint).

Documentation links

• BNB Chain MCP repo: https://github.com/bnb-chain/bnbchain-mcp
• npm: npx @bnb-chain/mcp@latest
• ERC-8004 (Identity Registry); Agent Metadata Profile for agentURI format.