nirholas/bnbchain-mcp

---

📋 Table of Contents

• What is BNB Chain MCP?
• Quick Start
• Features Overview
• Supported Networks
• Installation
• Configuration
• Data Sources
• Example Conversations
• Architecture
• Roadmap
• Related MCP Servers
• Troubleshooting
• Contributing
• License

---

🌟 What is BNB Chain MCP?

BNB Chain MCP is a Model Context Protocol (MCP) server optimized for BNB Chain and opBNB, while also supporting other EVM-compatible blockchains. It enables AI assistants like Claude, ChatGPT, and Cursor to interact with blockchain networks through natural language.

Why BNB Chain MCP?

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   User: "What's the current price of ETH and show me the best DEX pools"     │
│                                    │                                         │
│                                    ▼                                         │
│   ┌────────────────────────────────────────────────────────┐                 │
│   │              AI Assistant (Claude/ChatGPT)             │                 │
│   │                                                        │                 │
│   │         "Let me check that for you..."                 │                 │
│   └────────────────────────────────────────────────────────┘                 │
│                                    │                                         │
│                                    ▼                                         │
│   ┌───────────────────────────────────────────────────────┐                  │
│   │                  BNB Chain MCP Server                 │                  │
│   │                                                       │                  │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐            │                  │
│   │   │CoinGecko │  │GeckoTerm │  │DefiLlama │   ...      │                  │
│   │   └────┬─────┘  └────┬─────┘  └────┬─────┘            │                  │
│   └────────┼─────────────┼─────────────┼──────────────────┘                  │
│            │             │             │                                     │
│            ▼             ▼             ▼                                     │
│   ┌────────────────────────────────────────────────────────┐                 │
│   │                  Blockchain Networks                   │                 │
│   │   BNB Chain  │  Ethereum  │  Arbitrum  │  Polygon      │                 │
│   └────────────────────────────────────────────────────────┘                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Key Benefits

Use Cases

---

🚀 Quick Start

Get up and running in under 60 seconds!

Option 1: Claude Desktop (Recommended)

Add to your claude_desktop_config.json:

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

Option 2: Cursor / VS Code

Add to your MCP settings:

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

Option 3: ChatGPT Developer Mode

1. Enable Developer Mode in ChatGPT settings
2. Start the HTTP server:

   npx @nirholas/bnbchain-mcp@latest --http
   

3. In ChatGPT Settings → Apps, click Create app
4. Enter your server URL: http://localhost:3001/mcp
5. Select the app in conversations via Developer mode menu

📖 Full ChatGPT Setup Guide

Option 4: npx Instant Start

# stdio mode (Claude, Cursor)
npx @nirholas/bnbchain-mcp@latest

# HTTP mode (ChatGPT Developer Mode)
npx @nirholas/bnbchain-mcp@latest --http

# SSE mode (legacy clients)
npx @nirholas/bnbchain-mcp@latest --sse

---

🛠️ Features Overview

Feature Matrix

Tool Categories

---

🌐 Supported Networks

Adding Custom Networks

{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnbchain-mcp@latest"],
      "env": {
        "CUSTOM_RPC_56": "https://your-bnb-rpc.com",
        "CUSTOM_RPC_1": "https://your-eth-rpc.com"
      }
    }
  }
}

---

📦 Installation

Server Modes

From npm (Recommended)

# Run directly with npx (no install required)
npx @nirholas/bnbchain-mcp@latest

# Or install globally
npm install -g @nirholas/bnbchain-mcp

# Then run
bnbchain-mcp

From Source

# Clone
git clone https://github.com/nirholas/bnbchain-mcp
cd bnbchain-mcp

# Install dependencies
bun install

# Build
bun run build

# Run dev server (stdio - Claude)
bun dev

# Run dev server (HTTP - ChatGPT)
bun dev:http

# Run dev server (SSE - legacy)
bun dev:sse

Docker

# Build
docker build -t bnb-chain-mcp .

# Run stdio mode
docker run -it bnb-chain-mcp

# Run HTTP mode
docker run -p 3001:3001 bnb-chain-mcp --http

---

⚙️ Configuration

Environment Variables

Full Configuration Example

{
  "mcpServers": {
    "bnb-chain-mcp": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnbchain-mcp@latest"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "COINGECKO_API_KEY": "CG-xxx",
        "LUNARCRUSH_API_KEY": "xxx",
        "CUSTOM_RPC_56": "https://bsc-rpc.publicnode.com",
        "CUSTOM_RPC_1": "https://eth-rpc.publicnode.com",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Claude Desktop Configuration

---

📊 Data Sources

This MCP server integrates with the following APIs:

---

💬 Example Conversations

Price Queries

User: “What’s the current price of BNB?”

AI: Uses get_price tool → “BNB is currently trading at $XXX.XX, up 2.5% in the last 24 hours.”

Security Checks

User: “Is this token safe? 0x…”

AI: Uses check_token_security and detect_honeypot → “⚠️ Warning: This token has several red flags…”

DEX Analysis

User: “Show me the best BNB liquidity pools”

AI: Uses get_dex_pools → “Here are the top pools on BNB Chain by TVL…”

Multi-Chain Portfolio

User: “Check my wallet across all chains: 0x…”

AI: Uses get_portfolio → “Your total portfolio value is $X across 5 chains…”

DeFi Research

User: “What are the best yield farming opportunities on BNB Chain?”

AI: Uses get_yield_farms and get_tvl → “Here are the top yield opportunities…”

---

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                          BNB Chain MCP Server                                │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                        │
│  │    stdio     │  │     HTTP     │  │      SSE     │   Transport Layer      │
│  │   (Claude)   │  │   (ChatGPT)  │  │   (Legacy)   │                        │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                        │
│         │                 │                 │                                │
│         └─────────────────┼─────────────────┘                                │
│                           │                                                  │
│                           ▼                                                  │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                        MCP Protocol Handler                           │   │
│  │     Tools Registration  |  Resource Management  |  Prompt Templates   │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                           │                                                  │
│         ┌─────────────────┼─────────────────┐                                │
│         ▼                 ▼                 ▼                                │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐                          │
│  │ Blockchain │    │   Market   │    │  Security  │    Tool Categories       │
│  │   Tools    │    │    Data    │    │   Tools    │                          │
│  └─────┬──────┘    └─────┬──────┘    └─────┬──────┘                          │
│        │                 │                 │                                 │
│        ▼                 ▼                 ▼                                 │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                         Provider Integrations                         │   │
│  │   viem | CoinGecko | DefiLlama | GoPlus | LunarCrush | GeckoTerminal  │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                           │                                                  │
│                           ▼                                                  │
│  ┌───────────────────────────────────────────────────────────────────────┐   │
│  │                           EVM Networks                                │   │
│  │   BNB Chain | Ethereum | Arbitrum | Polygon | Base | Optimism | ...   │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Module Organization

src/
├── index.ts              # Entry point
├── server/
│   ├── stdio.ts          # stdio transport
│   ├── http.ts           # HTTP transport
│   └── sse.ts            # SSE transport
├── tools/
│   ├── blockchain/       # Core chain operations
│   ├── tokens/           # Token operations
│   ├── defi/             # DeFi protocols
│   ├── security/         # Security checks
│   ├── market/           # Market data
│   └── social/           # Social sentiment
├── providers/
│   ├── coingecko.ts      # CoinGecko API
│   ├── defillama.ts      # DefiLlama API
│   ├── goplus.ts         # GoPlus Security
│   └── ...
└── utils/
    ├── chains.ts         # Chain configurations
    ├── abi.ts            # Common ABIs
    └── format.ts         # Formatters

---

🔐 Security

Security Model

Best Practices

• ⚠️ Never share your PRIVATE_KEY in public configs
• ✅ Use environment variables or secrets management
• ✅ Use read-only mode when possible
• ✅ Always verify token safety before interacting
• ✅ Review transaction simulations before executing

---

❓ Troubleshooting

---

🗺️ Roadmap

A comprehensive roadmap of all crypto/blockchain/DeFi/Web3 features to be implemented.

Legend

• ✅ Implemented
• 🚧 In Progress
• 📋 Planned

---

🔗 Core Blockchain Operations

Network & Chain

Blocks

Transactions

Accounts/Wallets

---

💰 Token Operations

Native Tokens

ERC-20 (Fungible Tokens)

ERC-721 (NFTs)

ERC-1155 (Multi-Token)

Other Token Standards

---

🏦 DeFi - Decentralized Exchanges (DEX)

Swaps

DEX Analytics

Liquidity Provision

AMM Types Support

---

🏦 DeFi - Lending & Borrowing

Lending

Borrowing

Liquidations

Isolated Markets

---

🥩 DeFi - Staking

Native Staking

Liquid Staking

LP Staking/Farming

Restaking

---

📊 DeFi - Derivatives

Perpetual Futures

Options

Synthetics

---

🌉 Cross-Chain & Bridges

Bridging

Cross-Chain Messaging

Atomic Swaps

---

🗳️ Governance

Voting

Token Locking

Snapshot (Off-chain)

---

🔐 Security & Analysis

Contract Analysis

Token Security

Wallet Security

---

📈 Price & Market Data

Price Feeds

Analytics

---

🆔 Identity & Domains

ENS (Ethereum Name Service)

Other Name Services

DIDs & Verifiable Credentials

---

🖼️ NFT & Metaverse

NFT Marketplace

NFT Creation

NFT Finance

Metaverse

---

🔔 Events & Subscriptions

Event Listening

Webhooks & Notifications

---

📜 Smart Contract Interaction

Read Operations

Write Operations

Contract Deployment

---

🤖 Advanced Features

MEV & Flashbots

Account Abstraction (ERC-4337)

Intents & Solvers

Oracles

---

🛠️ Utility Functions

Gas

Encoding/Decoding

Address Utils

---

📰 Data & Information

News & Social

On-Chain Data

---

🏛️ Institutional & Compliance

KYC/AML

Custody

Reporting

---

Data Sources

This MCP server integrates with the following APIs:

---

🔗 Related MCP Servers

Related MCP servers, each maintained in its own repository:

Binance.com Server

Full Binance global API coverage including:

• Spot trading, wallet, staking, mining
• Convert, Simple Earn, Algo Trading (TWAP/VP)
• NFT, Pay, Copy Trading, Dual Investment
• VIP Loans, C2C/P2P, Fiat

{
  "mcpServers": {
    "binance": {
      "command": "npx",
      "args": ["ts-node", "binance-mcp-server/src/index.ts"],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_API_SECRET": "your_secret"
      }
    }
  }
}

Binance.US Server

US-regulated exchange with:

• Market data, spot trading, wallet
• Staking, OTC, sub-accounts
• Custodial solutions (institutional)

{
  "mcpServers": {
    "binance-us": {
      "command": "node",
      "args": ["binance-us-mcp-server/build/index.js"],
      "env": {
        "BINANCE_US_API_KEY": "your_key",
        "BINANCE_US_API_SECRET": "your_secret"
      }
    }
  }
}

---

🤝 Contributing

We welcome contributions! Here’s how to get started:

Development Setup

# Fork and clone
git clone https://github.com/nirholas/bnbchain-mcp
cd bnbchain-mcp

# Install dependencies
bun install

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

# Make changes and test
bun dev
bun test

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

# Open Pull Request

Contribution Guidelines

• 📝 Follow existing code style
• ✅ Add tests for new features
• 📖 Update documentation
• 🔍 Run linting before committing

Adding New Tools

1. Create tool file in src/tools//
2. Export tool definition with Zod schema
3. Add to tool index
4. Document in README

---

📄 License

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

---

🙏 Credits

Built by nich (github.com/nirholas) and the Sperax Team (github.com/speraxos) (github.com/sperax)

Special Thanks

• Model Context Protocol team
• viem for excellent EVM tooling
• All the amazing Web3 API providers

---

---

🌐 Live HTTP Deployment

BNBChain MCP is deployed and accessible over HTTP via MCP Streamable HTTP transport — no local installation required.

Endpoint:

https://modelcontextprotocol.name/mcp/bnbchain-mcp

Connect from any MCP Client

Add to your MCP client configuration (Claude Desktop, Cursor, SperaxOS, etc.):

{
  "mcpServers": {
    "bnbchain-mcp": {
      "type": "http",
      "url": "https://modelcontextprotocol.name/mcp/bnbchain-mcp"
    }
  }
}

Available Tools (6)

Example Requests

Get crypto prices:

curl -X POST https://modelcontextprotocol.name/mcp/bnbchain-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_price","arguments":{"ids":"binancecoin","vs_currencies":"usd"}}}'

Market overview:

curl -X POST https://modelcontextprotocol.name/mcp/bnbchain-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_market_overview","arguments":{"limit":10}}}'

Search:

curl -X POST https://modelcontextprotocol.name/mcp/bnbchain-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_coins","arguments":{"query":"bnb"}}}'

List All Tools

curl -X POST https://modelcontextprotocol.name/mcp/bnbchain-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Also Available On

• SperaxOS — Browse and install from the MCP marketplace
• All 27 MCP servers — See the full catalog at modelcontextprotocol.name

Powered by modelcontextprotocol.name — the open MCP HTTP gateway

Documentation

Full documentation site: https://nirholas.github.io/bnbchain-mcp/

• Getting started covers install and first run.
• Examples has copy-paste snippets.

Star History