Tairon-ai/bnb-mcp

🚀 Features

💼 Wallet Management

• Create new BNB Chain wallets with secure key generation
• Generate mnemonic phrases for wallet recovery
• Export wallet addresses and private keys
• Support for multiple wallet formats
• HD wallet derivation support
• Secure credential management

💰 Balance Checking

• Check native BNB balances instantly
• Query BEP20 token balances (USDT, USDC, CAKE, BUSD, DAI, WBNB)
• Support for custom token contract addresses
• Batch balance queries for multiple tokens
• Real-time balance updates from BNB Chain network
• Complete token information (decimals, total supply, symbol)

🔄 Token Transfers

• Send BNB to any BNB Chain address
• Transfer BEP20 tokens with automatic decimal handling
• Gas estimation and optimization
• Transaction status tracking
• Transaction receipt with block explorer links
• Support for custom gas prices and limits

🔀 Token Swaps (PancakeSwap V3 Smart Router)

• V3 Smart Router Integration - Automatically routes through V2, V3, and StableSwap pools for best prices
• Exact Input Swaps - Specify input amount, get optimal output
• Exact Output Swaps - Specify desired output amount, router calculates required input
• Swap BNB for any BEP20 token
• Swap BEP20 tokens for BNB
• Swap between any BEP20 tokens
• Automatic routing through WBNB for optimal liquidity
• Configurable slippage protection (default 0.5%)
• Automatic token approval handling
• 0.25% fee tier optimization

📊 Price Oracle (Binance Oracle)

• Real-time Price Data - Get current token prices from official Binance Oracle
• Multi-token Support - Query single or multiple token prices in one request
• Auto Stablecoin Normalization - All stablecoins (USDT, USDC, BUSD, DAI) automatically converted to USD
• Available Symbols - Get list of all tradable pairs from oracle
• No API Keys Required - Direct access to Binance Oracle public API

🏛️ Enterprise-Ready Architecture

• Built with ethers.js v6 for robust blockchain interactions
• Comprehensive error handling with user-friendly messages
• Optimized for BNB Chain Mainnet with configurable RPC endpoints
• Docker containerization support
• Production-tested components
• MCP protocol 2024-11-05 implementation
• 11 specialized tools for blockchain operations
• Zero-configuration deployment with sensible defaults

📦 Quick Start

Note: This MCP server provides seamless BNB Chain blockchain integration with wallet management, balance queries, and token transfers. No API keys required - just configure your RPC endpoint and start building!

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm >= 9.0.0

🔑 Configuration

Important: Private keys and mnemonics are sensitive data. Never commit them to version control or share them publicly.

• BNB_RPC_URL: Custom RPC endpoint (optional, defaults to public BNB Chain node)
• WALLET_ADDRESS: Default wallet for balance checks (optional)
• WALLET_PRIVATE_KEY: Private key for transactions (optional, can be provided per-request)
• PORT: HTTP server port (default: 8080)

For transaction operations, you can either set WALLET_PRIVATE_KEY in environment or pass it directly to transaction tools.

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/bnb-mcp.git
cd bnb-mcp/mcp-server

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env
# Edit .env with your configuration if needed

# Start the HTTP server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "bnb-network": {
      "command": "node",
      "args": ["/path/to/bnb-mcp/mcp/index.js"],
      "env": {
        "BNB_RPC_URL": "https://bsc.publicnode.com",
        "WALLET_ADDRESS": "your_default_wallet_address",
        "WALLET_PRIVATE_KEY": "your_private_key_for_transactions"
      }
    }
  }
}

Note: WALLET_ADDRESS and WALLET_PRIVATE_KEY are optional. You can provide them per-request or set defaults in the configuration.

🛠 Available Tools

💼 Wallet Management

💰 Balance Queries

🔄 Transactions

🔀 Token Swaps (V3 Smart Router)

📊 Price Oracle (Binance Oracle)

🤖 Prompts

💬 Example Prompts for AI Assistants

💼 Wallet Operations

"Create a new BNB Chain wallet for me"
"Generate a new wallet and show me the address"
"I need a new BNB wallet with mnemonic phrase"
"Create a wallet for receiving payments"
"Generate a fresh BNB Chain address"

💰 Balance Checking

"Check my BNB balance for address 0x..."
"What's my USDT balance?"
"Show all token balances for my wallet"
"How much CAKE do I have?"
"Check the balance of USDC in my wallet"
"What tokens do I have in address 0x...?"

🔄 Token Transfers

"Send 0.01 BNB to address 0x..."
"Transfer 5 USDT to 0x..."
"Send 2 CAKE tokens to my friend's wallet 0x..."
"I need to transfer 3 USDC to 0x..."
"Move 0.05 BNB from my wallet to 0x..."

🔀 Token Swaps

"Swap 0.01 BNB for USDT using V3 Smart Router"
"Exchange 5 USDT to CAKE"
"Convert 2 CAKE to BNB"
"Swap my BUSD to USDC with 0.5% slippage"
"Trade 0.05 BNB for DAI on PancakeSwap V3"
"I want to swap 3 USDT for WBNB"
"Swap 0.01 BNB to DAI"
"Exchange 2 USDT for CAKE"

📊 Information Queries

"What BEP20 tokens are supported?"
"Show me the list of available tokens"
"What's the contract address for USDT on BNB Chain?"
"Can you list all supported tokens?"
"What tokens can I trade on this server?"

💰 Price Oracle Queries

"What's the current price of BTC?"
"Get me the BTC/USDT price"
"Show current prices for BTC, ETH, and BNB"
"What's Bitcoin trading at right now?"
"Current price of BNB in USD"
"Get prices for BTC/USDT, ETH/USDC, and BNB/BUSD"
"What trading pairs are available in the oracle?"
"Show me all available symbols from Binance Oracle"
"Get real-time price for ETH"

🔍 Advanced Queries

"Check USDT balance and show token details"
"Get complete balance overview for my wallet"
"Show me all my holdings on BNB Chain"
"What's the total supply of CAKE token?"
"Check balance and give me BSCScan link"

🔒 Security

🛡️ Security Features

• Secure Key Generation - Cryptographically secure random wallet generation using ethers.js
• Private Key Protection - Private keys never logged or exposed in error messages
• Address Validation - All addresses validated before transactions
• Gas Estimation - Automatic gas price fetching and transaction simulation
• Balance Checks - Insufficient balance detection before transaction submission
• Network Isolation - Configurable RPC endpoints for production/testing
• Error Sanitization - Sensitive data stripped from error responses

🔐 Best Practices

• Never Commit Keys: Never commit .env files or private keys to version control
• Use Environment Variables: Store sensitive data in environment variables, not hardcoded
• Secure RPC Endpoints: Use trusted RPC endpoints or run your own node
• Transaction Verification: Always verify transaction details before confirmation
• Rate Limiting: Configure appropriate rate limits for RPC requests
• Monitor Transactions: Track all transactions via BSCScan links provided in responses

📊 Supported Infrastructure

🌐 Network Details

• Network: BNB Chain Mainnet
  • RPC (Default): https://bsc.publicnode.com
  • RPC (Fallbacks): Multiple endpoints available (Binance, PublicNode, 1RPC, etc.)
  • Chain ID: 56
  • Currency: BNB
  • Block Explorer: https://bscscan.com

📊 Supported BEP20 Tokens

• USDT - Tether USD (0x55d398326f99059fF775485246999027B3197955)
• USDC - USD Coin (0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d)
• CAKE - PancakeSwap Token (0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82)
• BUSD - Binance USD (0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56)
• DAI - Dai Stablecoin (0x1AF3F329e8BE154074D8769D1FFa4eE058B1DBc3)
• WBNB - Wrapped BNB (0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c)

⚡ Performance

• Response Time: < 2s for balance queries
• Transaction Speed: ~3 seconds (BNB Chain block time)
• RPC Reliability: Multiple fallback endpoints available
• Rate Limiting: 10 requests/second (configurable)

🚀 Deployment

🏭 Production Deployment

# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start server.js --name bnb-mcp

# With Docker
docker build -t bnb-mcp .
docker run -d -p 8080:8080 --env-file .env bnb-mcp

🔑 Environment Variables

# BNB Chain Configuration
BNB_RPC_URL=https://bsc.publicnode.com

# Wallet Configuration (Optional)
WALLET_ADDRESS=your_default_wallet_address
WALLET_PRIVATE_KEY=your_private_key

# Server Configuration
PORT=8080
NODE_ENV=production

# Advanced Settings
RATE_LIMIT_REQUESTS_PER_SECOND=10

📈 Performance

• Fast Balance Queries: Direct RPC calls with < 2 second response time
• Efficient Token Handling: Batch queries for multiple token balances
• Optimized Gas Usage: Automatic gas price fetching and optimization
• Reliable Transactions: Transaction confirmation with receipt verification
• Scalable Architecture: Supports concurrent requests with rate limiting
• Low Latency: Direct connection to BNB Chain nodes for minimal delay

🎯 Key Features

✨ Developer-Friendly

• Simple JSON-RPC interface
• Comprehensive error messages
• BSCScan links for all transactions
• TypeScript support ready
• Well-documented API

🔄 Production-Ready

• Docker containerization
• PM2 process management support
• Environment-based configuration
• Graceful error handling
• Rate limiting and throttling

🛤️ Extensible Design

• Easy to add new token contracts
• Modular tool architecture
• Pluggable RPC providers
• Custom network support ready

🤝 Contributing

We welcome contributions!

# Fork the repository on GitHub, then clone
git clone https://github.com/Tairon-ai/bnb-mcp.git

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
npm test

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request

Please read for details on our code of conduct and development process.

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• ethers.js - Ethereum and BNB Chain blockchain interaction library
• MCP Protocol - Model Context Protocol specification
• BNB Chain - BNB Chain blockchain infrastructure
• BSCScan - Block explorer and analytics platform

📚 Resources

• BNB Chain Documentation
• ethers.js Documentation
• MCP Protocol Specification
• BEP20 Token Standard

📝 Additional Information

Supported Operations

Current implementation includes:

• ✅ Wallet generation with mnemonic
• ✅ BNB balance checking
• ✅ BEP20 token balance checking
• ✅ BNB transfers
• ✅ BEP20 token transfers
• ✅ Token information queries
• ✅ Multiple token support

Recent Updates

Latest features:

• ✅ Binance Oracle Integration - Real-time price data with auto stablecoin normalization
• ✅ Multi-token Price Queries - Get prices for multiple tokens in one request
• ✅ PancakeSwap V3 Smart Router Integration - Automatically routes through V2, V3, and StableSwap
• ✅ Exact Input Swaps - Specify input amount for optimal output
• ✅ Exact Output Swaps - Specify desired output, router calculates input needed
• ✅ Token swaps via PancakeSwap (BNB ↔ Token, Token ↔ Token)
• ✅ Automatic token approval handling

Future Enhancements

Planned features:

• ✨ Smart contract interaction
• ✨ NFT support (BEP721/BEP1155)
• ✨ Advanced routing strategies
• ✨ Staking operations
• ✨ Multi-signature wallet support