Bnbchain Mcp

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.

ERC-8004 agent tools reference

Register and resolve AI agents on the ERC-8004 Identity Registry. Supported networks: BSC (56), BSC Testnet (97), Ethereum, Base, Polygon, and their testnets where the official registry is deployed.

agentURI must point to a JSON metadata file following the Agent Metadata Profile: name, description, image, and services (e.g. MCP endpoint).

---

register_erc8004_agent (write)

Register an agent on the ERC-8004 Identity Registry. Mints an on-chain agent identity (NFT) and returns the agent ID.

Returns: agentId (string), txHash, network.

Example: After registration, owners can verify on 8004scan (mainnet or testnet).

---

set_erc8004_agent_uri (write)

Update the metadata URI for an existing ERC-8004 agent. Caller must be the owner of the agent NFT.

Returns: success, txHash, agentId, network.

---

get_erc8004_agent (read-only)

Get agent info from the ERC-8004 Identity Registry: owner address and tokenURI (metadata URI).

Returns: agentId, owner, tokenURI, network.

---

get_erc8004_agent_wallet (read-only)

Get the verified payment wallet address for an ERC-8004 agent (for x402 / agent payments). Set on-chain via setAgentWallet; defaults to owner on registration.

Returns: agentId, agentWallet, network.

EVM tools reference

`network`: string like bsc, opbnb, ethereum, base, or chain ID. Use get_supported_networks to list options.

• Read-only tools: network is optional; default is bsc.
• Write tools (transfer_native_token, transfer_erc20, transfer_nft, transfer_erc1155, approve_token_spending, write_contract): `network` is REQUIRED. No default. If the user does not specify the network, the agent MUST ask before calling; do not default to mainnet.

Tools that require PRIVATE_KEY in the MCP server env are marked with (write).

---

Blocks

---

Transactions

---

Network

---

Wallet and balances

(Write) — require PRIVATE_KEY in env:

---

Contracts

read_contract: Pass the ABI of the single function (or full contract ABI). Example args: [] or ["0x...", "123"].

---

Tokens (ERC20)

---

NFT (ERC721 / ERC1155)

Transfer tools: see Wallet and balances above (transfer_nft, transfer_erc1155).

---

ENS

Note: ENS is not supported on BSC; use on Ethereum or other chains where ENS is deployed.

Greenfield tools reference

Greenfield tools operate on testnet or mainnet. Use `network`: "testnet" (default) or "mainnet". Writes require PRIVATE_KEY in the MCP server env (or passed where supported).

Note: Some tools may be named differently in the implementation (e.g. file upload). Use the tool names exposed by the MCP server; below matches the BNB Chain MCP README and common usage.

---

Buckets

bucketName defaults to created-by-bnbchain-mcp when optional.

---

Objects and folders

If the server exposes gnfd_create_file instead of gnfd_upload_object, use filePath (absolute path to the file to upload).

---

Account and payment

Use get_supported_networks or the MCP server’s tool list to confirm exact parameter names for the version in use.

MCP prompts reference

The BNB Chain MCP server exposes prompts that return guided analysis or explanations. Use these prompt names when invoking MCP prompts (e.g. from Cursor or Claude).

Prompts typically accept input (e.g. block number, tx hash, address) as specified by the MCP server. Prefer these prompts when the user asks for “analysis,” “explanation,” or “how to” rather than a single raw tool call.