Interact with the BNB Chain Model Context Protocol (MCP) server. Blocks, contracts, tokens, NFTs, wallet, Greenfield, and ERC-8004 agent tools. Use npx @bnb-...
--- name: bnbchain-mcp displayName: bnbchain-mcp version: 1.0.2 description: Interact with the BNB Chain Model Context Protocol (MCP) server. Blocks, contracts, tokens, NFTs, wallet, Greenfield, and ERC-8004 agent tools. Use npx @bnb-chain/mcp@latest or read the official skill page. --- # BNB Chain MCP Skill This skill allows you to interact with the BNB Chain MCP server to retrieve data and perform actions on BNB Chain and other EVM-compatible networks. --- ## Before you install - **Credentials:** Signing keys and RPC endpoints are supplied by you (see *Credentials and environment* below). Never paste private keys into a UI or an env var you don’t control. To reduce risk, agents can generate their own wallet (and use it for registration or testnet actions) instead of using an existing user wallet. Ask the skill author or [documentation](https://github.com/bnb-chain/bnbchain-mcp) how they are stored and who can access them. - **Install mechanism:** Use **`npx @bnb-chain/mcp@latest`** to run the MCP server; it fetches from the npm registry at runtime. If you prefer to audit first, install the package locally and review the [source code](https://github.com/bnb-chain/bnbchain-mcp) before use. - **Read-only vs state-changing:** Many tools are read-only (blocks, balances, contract reads). Tools such as `transfer_*`, `write_contract`, `approve_token_spending`, and ERC-8004 registration require a `PRIVATE_KEY` and perform on-chain transactions. If you want read-only use only, do not supply a private key and avoid invoking state-changing tools. - **Sandbox and testnet:** Run in a restricted environment when possible. Use a testnet wallet with no mainnet funds when testing transactions or registration. - **Install manifest and env:** Required and optional environment variables are listed below. Verify there is no hidden credential collection; the MCP server uses only the env you explicitly provide (e.g. in your MCP client config). --- ## 1. How to connect Use **`npx @bnb-chain/mcp@latest`** to connect to the BNB Chain MCP server. --- ## 2. Credentials and environment - **RPC / network:** The MCP server uses public or configured RPC endpoints for supported chains (BSC, opBNB, Greenfield, etc.). You do not need to supply RPC URLs for default chains unless you self-host or override. - **Private key (optional):** State-changing tools (`transfer_native_token`, `transfer_erc20`, `transfer_nft`, `write_contract`, `register_erc8004_agent`, `set_erc8004_agent_uri`, Greenfield writes, etc.) require a **`PRIVATE_KEY`** in the environment where the MCP server runs (e.g. in your Cursor/Claude MCP config). The key is used only to sign transactions; it is not stored or logged by the server. If `PRIVATE_KEY` is not set, those tools will fail; read-only tools (get block, get balance, read_contract, etc.) work without it. - **Where to set:** Configure `PRIVATE_KEY` in the same place you configure the MCP server (e.g. `env` in `mcpServers.bnbchain-mcp` in your client’s config). Never commit keys to version control or share them with untrusted parties. - **Summary:** No credentials are required for read-only use. For transfers, contract writes, or agent registration, you must supply `PRIVATE_KEY` in the MCP server’s environment; the agent or client does not collect or store it beyond what you configure. --- ## 3. Agent registration **First:** Register yourself on-chain using the MCP tool **`register_erc8004_agent`** (see ERC-8004 Agent tools below). **Then** owners can check registration on the scan site: - **Mainnet:** **[https://www.8004scan.io/](https://www.8004scan.io/)** - **Testnet:** Agents should inform their owners to visit **[https://testnet.8004scan.io/](https://testnet.8004scan.io/)** to see their registration --- ## 4. Available Prompts and Tools *(From [BNBChain MCP README](https://github.com/bnb-chain/bnbchain-mcp).)* ### 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 **Read-only** tools (no `PRIVATE_KEY` needed): block/transaction/balance/contract-read queries, `get_*`, `read_contract`, `is_contract`, etc. **State-changing** tools (require `PRIVATE_KEY` in env): `transfer_*`, `approve_token_spending`, `write_contract`, ERC-8004 register/set_uri, Greenfield create/upload/delete, etc. ### Network parameter Most EVM tools accept **`network`** (e.g. `bsc`, `opbnb`, `ethereum`, `base`). Use **`get_supported_networks`** to list options. - **Read-only tools** (blocks, balances, contract reads, `get_chain_info`, etc.): **`network`** is optional; default is `bsc`. - **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. | 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 EOA | | read_contract | Read data from a smart contract (view/pure function) | | write_contract | Write data to a smart contract (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](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry. Supported networks: BSC (56), BSC Testnet (97), Ethereum, Base, Polygon, and their testnets where the [official registry](https://github.com/erc-8004/erc-8004-contracts) is deployed. The `agentURI` should point to a JSON metadata file following the [Agent Metadata Profile](https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html). | Name | Description | | ----------------------- | --------------------------------------------------------------------------- | | register_erc8004_agent | Register yourself on the ERC-8004 Identity Registry (do this before checking the scan site); 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 | --- ## 5. 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, Greenfield writes), 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.
don't have the plugin yet? install it then click "run inline in claude" again.
split monolithic guide into six distinct components with explicit decision trees for network selection and write-vs-read logic, added edge cases (rate limits, nonce mismatches, abi issues, timeout handling), clarified private key scoping and environment setup, added block explorer linking patterns, and included erc-8004 and greenfield workflows.
---
name: bnbchain
slug: bnbchain
source: clawhub
description: interact with bnb chain mcp server. blocks, contracts, tokens, nfts, wallet, greenfield, erc-8004 agent tools.
---
# bnbchain
## intent
use the bnb chain model context protocol (mcp) server to query blockchain data and execute transactions on bsc, opbnb, ethereum, base, polygon, and other evm-compatible networks. read block info, balances, contract state, token/nft metadata. write transactions, approve token spending, transfer assets, register erc-8004 agents, and manage greenfield buckets and objects. use this skill when you need deterministic on-chain reads, need to sign and broadcast transactions, or need to interact with decentralized storage. never run this without understanding the network you're targeting and whether a transaction is destructive.
## inputs
### external connections
**bnb chain mcp server:** npx @bnb-chain/mcp@latest. fetches from npm registry at install time. audit the source code at https://github.com/bnb-chain/bnbchain-mcp before use if you need to review dependencies or signing logic.
### environment variables
**PRIVATE_KEY** (optional but required for writes): hex-encoded private key for signing transactions, approvals, contract writes, erc-8004 registration, and greenfield operations. set in the mcp server's environment (e.g. in your claude/cursor mcp config), not passed as a chat parameter or stored in version control. the server uses it only to sign; it does not log, store, or transmit the key. omit this if you only need read-only access (blocks, balances, contract reads, nft metadata).
**RPC endpoints:** the mcp server uses public rpc endpoints for bsc, opbnb, ethereum, base, polygon, and greenfield by default. no configuration needed unless you self-host or override with custom rpc urls.
### supported networks
use get_supported_networks to list all available networks. common networks: bsc (mainnet), bsc-testnet, opbnb (mainnet), ethereum, ethereum-sepolia, base, base-sepolia, polygon, polygon-mumbai, greenfield (storage chain).
### user inputs required
- network name (e.g. "bsc", "ethereum", "base-sepolia"): mandatory for any write operation (transfer, contract write, approve, erc-8004 register, greenfield create/upload). optional for reads; defaults to bsc if omitted.
- recipient address or contract address: for transfers and approvals.
- amounts, token addresses, contract abi, function parameters: context-specific; see procedure.
- agentURI (json metadata url): required for erc-8004 registration; must follow the agent metadata profile at https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html.
## procedure
### 1. verify the network and private key availability
**inputs:** user intent (read-only or write), desired network name.
**steps:**
- if the user requests a write operation (transfer, approve, write_contract, register_erc8004_agent, greenfield create/upload/delete), ask the user to confirm the network name explicitly. do not assume or default to bsc or mainnet.
- confirm that PRIVATE_KEY is set in the mcp server environment if writes are needed. if the user reports "tool failed" or "no signer", PRIVATE_KEY is likely missing; guide them to set it in their mcp config.
- if the user only needs reads (get_block, get_balance, read_contract, get_nft_info), network is optional and defaults to bsc.
**outputs:** confirmed network name (string), confirmation that private key is available (boolean, only for writes).
**edge cases:**
- user specifies mainnet without understanding the risk: warn explicitly that testnet is safer for development.
- network name is invalid or not in supported list: call get_supported_networks and show the user valid options.
- user wants to write but has not generated or provided a wallet: offer to generate a new wallet and fund it on testnet first.
### 2. call the appropriate tool
**inputs:** tool name, network (if required), parameters (address, amount, abi, etc.).
**steps:**
- select the tool from the available tools table below, e.g. get_block_by_number, transfer_native_token, read_contract, gnfd_upload_object.
- pass network as a parameter for writes; omit or use default (bsc) for reads unless the user specifies otherwise.
- for transfers: pass recipient, amount, network. the tool derives the sender from PRIVATE_KEY.
- for contract writes: pass contract address, function name, parameters, abi (or let the tool infer), network.
- for erc-8004 registration: pass agentURI, network. the tool returns an agent ID.
- for greenfield operations: pass bucket name, object name, file data (upload), network. greenfield uses the same PRIVATE_KEY for auth.
**outputs:** transaction hash (for writes), data (for reads), or error message.
**edge cases:**
- rate limiting: if the rpc endpoint returns a 429 or rate limit error, wait 5-10 seconds and retry.
- insufficient gas: estimate_gas before sending. if gas estimate fails, the recipient or contract may not exist, or network may be misconfigured.
- invalid abi: read_contract and write_contract require a valid json abi matching the contract. if the abi is missing or malformed, the tool will fail; fetch the abi from a block explorer (e.g. bscscan, etherscan) and re-call.
- expired signature / nonce mismatch: if a write tool fails with "nonce too low" or "signature expired", the account may have multiple pending transactions or the network may have reorged; wait a few seconds and retry, or check the latest nonce via web3.
- empty result sets: get_nft_balance, get_erc20_balance, and similar read tools return 0 or empty arrays if the address holds no tokens; this is not an error.
- network timeout: if the rpc endpoint is unreachable, the tool will timeout after ~30 seconds; catch the timeout and suggest retrying with a different rpc or checking network status.
### 3. interpret and present the result
**inputs:** tool output (transaction hash, data, error, or null).
**steps:**
- for writes (transfer, approve, write_contract, erc-8004 register, greenfield create): present the transaction hash and a link to the block explorer (e.g. https://bscscan.com/tx/{hash} for bsc).
- for reads (get_balance, get_nft_info, read_contract): parse the return value (number, string, object, array) and explain it in plain language.
- for erc-8004 registration: present the agent ID and a link to check registration: https://www.8004scan.io/ (mainnet) or https://testnet.8004scan.io/ (testnet).
- for greenfield: present the bucket/object name and storage status.
**outputs:** human-readable summary, explorer links, next steps if applicable.
**edge cases:**
- user calls a read tool but gets "private key missing" error: this indicates the tool internally requires a write capability (e.g. a view function that reads private storage); clarify with the tool author or use a different tool.
- tool returns hex-encoded data instead of decoded values: this can happen if the abi is missing or incorrect; offer to help decode the hex using the abi.
### 4. confirm receipt and finality (writes only)
**inputs:** transaction hash, network.
**steps:**
- after a write operation, offer to check the transaction status via get_transaction_receipt.
- poll the receipt until status is "success" (1) or "failed" (0).
- if success, the transaction is mined and state is finalized on bsc/opbnb (instant) or ethereum/base (12+ block confirmations).
- if failed, parse the revert reason and explain why (insufficient balance, contract reverted, etc.).
**outputs:** confirmation of finality, or error reason.
**edge cases:**
- transaction is pending for >5 minutes: the network may be congested or the gas price may be too low. offer to check mempool status or speed up the tx via a replacement transaction (if supported by the network and wallet).
- transaction is dropped from mempool: the nonce may be out of order or the sender's account was reset; advise the user to check the latest nonce and resubmit.
### available tools reference
**read-only (no private key needed):**
- get_block_by_hash, get_block_by_number, get_latest_block
- get_transaction, get_transaction_receipt, estimate_gas
- get_chain_info, get_supported_networks
- is_contract, resolve_ens
- get_address_from_private_key (derives address from a private key without signing)
- read_contract (calls a view/pure function)
- get_erc20_token_info, get_native_balance, get_erc20_balance
- get_nft_info, check_nft_ownership, get_nft_balance
- get_erc1155_token_metadata, get_erc1155_balance
- get_erc8004_agent, get_erc8004_agent_wallet
- gnfd_get_bucket_info, gnfd_list_buckets, gnfd_get_object_info, gnfd_list_objects, gnfd_get_account_balance, gnfd_get_payment_account_info, gnfd_get_payment_balance
**state-changing (require private key in environment):**
- transfer_native_token (network required)
- transfer_erc20 (network required)
- transfer_nft (network required)
- transfer_erc1155 (network required)
- approve_token_spending (network required)
- write_contract (network required)
- register_erc8004_agent (network required)
- set_erc8004_agent_uri (network required)
- gnfd_create_bucket, gnfd_delete_bucket, gnfd_upload_object, gnfd_download_object, gnfd_delete_object, gnfd_create_folder (all require network and greenfield auth)
- gnfd_deposit_to_payment, gnfd_withdraw_from_payment, gnfd_disable_refund, gnfd_create_payment (all require network)
## decision points
**read-only vs. state-changing:**
- if the user asks for a balance, block info, contract state, or metadata (nft, token, agent info), use read-only tools. no private key needed.
- if the user wants to transfer, approve, write contract state, register an agent, or manage greenfield storage, use state-changing tools. private key must be in the mcp server environment.
**network selection for writes:**
- if the user specifies a network explicitly (e.g. "on bsc mainnet", "on base-sepolia"), use it and pass it to the tool.
- if the user does not specify a network and requests a write, ask the user to confirm the network name before calling the tool. do not default to bsc or any mainnet. offer testnet as the safe default for development.
- if the user specifies mainnet for a high-value transaction without context, warn them and ask for confirmation.
**private key availability:**
- if a write tool fails with "no signer" or "private key not found", the PRIVATE_KEY env var is missing. guide the user to set it in their mcp config (e.g. in claude/cursor settings, under "env" for the bnbchain-mcp server).
- if the user wants to write but has not set up a wallet, offer to help generate one and fund it on testnet.
**erc-8004 agent registration workflow:**
- if the user is an ai agent and wants to be discoverable via the erc-8004 identity registry, call register_erc8004_agent with an agentURI (json metadata file). the tool returns an agent ID.
- after registration, inform the user to check https://www.8004scan.io/ (mainnet) or https://testnet.8004scan.io/ (testnet) to verify registration.
- if the user later wants to update metadata, call set_erc8004_agent_uri (owner only).
**greenfield storage:**
- if the user needs to store files on-chain (not just read them), use gnfd_create_bucket and gnfd_upload_object. these require network and private key.
- if the user needs to manage payments for greenfield storage, use gnfd_deposit_to_payment and gnfd_get_payment_balance.
- gnfd_disable_refund is irreversible; confirm before calling.
**error handling and retry:**
- if estimate_gas fails, the transaction is likely invalid (bad recipient, contract revert, etc.); do not call transfer_native_token or write_contract without fixing the underlying issue.
- if a transaction fails on-chain (status 0 in receipt), parse the revert reason and explain what went wrong. do not retry automatically; ask the user to fix the issue first.
- if an rpc endpoint is slow or returns a rate limit error, wait 5-10 seconds and retry. if the error persists, suggest checking network status or using a different rpc.
## output contract
**for read operations:**
- return a structured json object (parsed from the blockchain) or a formatted text summary.
- include block number, timestamp, contract state, balance, token metadata, or nft info as applicable.
- include a direct link to the block explorer (e.g. bscscan.com, etherscan.io) if relevant.
**for write operations:**
- return the transaction hash (40 hex chars, prefixed with 0x).
- include a block explorer link in the format: https://{network-domain}/tx/{hash}.
- for erc-8004 registration, also return the agent ID.
- for greenfield operations, return the bucket/object name and storage status.
**for errors:**
- return the error type (rpc error, invalid abi, insufficient gas, nonce mismatch, rate limit, timeout) and a plain-language explanation.
- suggest the corrective action (set env var, confirm network, fetch abi, wait and retry, increase gas price, etc.).
**file locations:** no files are written to disk by this skill. all data is on-chain or returned to the user in chat.
## outcome signal
- **read-only operations:** the user can see the blockchain data (balance, block, contract state, nft metadata) printed in chat. they can verify it by clicking the explorer link and checking on-chain.
- **write operations:** the user receives a transaction hash and can watch it confirm on the block explorer. after confirmation, the on-chain state changes (balance transfers, contract state updates, agent registration visible on 8004scan.io, greenfield object stored).
- **private key setup:** if a write fails with "no signer", the outcome signal is the user setting PRIVATE_KEY in their mcp config and retrying. after successful retry, the transaction hash appears.
- **network confirmation:** if the user doesn't specify a network for a write, the outcome signal is the user confirming the network name so you can call the tool safely.
- **erc-8004 registration:** the outcome signal is the agent ID returned by register_erc8004_agent, and the user seeing their agent listed on https://www.8004scan.io/ or https://testnet.8004scan.io/ within 1-2 blocks.
- **greenfield storage:** the outcome signal is the bucket/object name confirmed as created or uploaded, and a link to check storage status.
---
**credits:** bnb chain mcp server authors and community. source: https://github.com/bnb-chain/bnbchain-mcp.