Getting Started

A step-by-step guide from zero to running. No prior blockchain experience needed.

Estimated time: 10-15 minutes for basic setup, 5 more for your first MCP server.

Before You Start

What You'll Need

You need three tools installed on your computer. If you already have them, skip ahead to Step 1.

Tool	What It Does	How to Check	Install Link
Git	Downloads the project	`git --version` → any version is fine	git-scm.com
Node.js 18+	Runs JavaScript code	`node --version` → should show v18 or higher	nodejs.org
bun	Fast package manager and runner	`bun --version` → any version is fine	bun.sh

How to install bun (MacOS / Linux / WSL)

Open your terminal and run:

curl -fsSL https://bun.sh/install | bash

Then restart your terminal (close and reopen it) so the bun command becomes available.

Verify it worked:

bun --version
# Should print something like 1.x.x

How to install bun on Windows

Open PowerShell and run:

powershell -c "irm bun.sh/install.ps1 | iex"

Or if you have npm already: npm install -g bun

Then restart your terminal.

What if I don't want to install bun?

No problem — you can use npm or yarn instead. Anywhere this guide says bun install, use npm install. Anywhere it says bun run build, use npm run build. Everything works the same way.

What You Won't Need (Yet)

You do not need:

A crypto wallet (unless you want to execute on-chain transactions)
Any cryptocurrency or tokens
API keys (basic features work without them)
Docker (optional, for deployment only)

Step 1: Download the Toolkit

Open your terminal (Terminal on Mac/Linux, PowerShell on Windows) and run:

git clone https://github.com/nirholas/bnb-chain-toolkit.git
cd bnb-chain-toolkit

This downloads the entire toolkit to a folder called bnb-chain-toolkit and moves you into it.

What if git clone fails?

Common fixes:

"git: command not found" → Install Git from git-scm.com
"Permission denied" → You may need to set up SSH keys. Try the HTTPS method instead (which is what's shown above)
Slow download → The repo is large. Wait it out, or use git clone --depth 1 ... to download only the latest version

Step 2: Install Dependencies

bun install

This installs all the JavaScript packages the toolkit needs. It typically takes 30-60 seconds.

What you should see: A progress bar, then a success message like "done in X.XXs".

What if bun install fails?

Permission errors: Don't use sudo. Delete node_modules and retry:
```
rm -rf node_modules && bun install
```
Network errors: Check your internet connection, or try a different network
Version errors: Ensure Node.js 18+ is installed: node --version

Step 3: Build the Agent Index

bun run build

This processes all 78 agent definitions and creates a searchable index at public/index.json.

What you should see: Output describing the build process, ending in a success message.

Step 4: Verify Everything Works

Run this quick check:

# Confirm the agent index was built
cat public/index.json | head -5

Expected output: You should see the start of a JSON file with agent data:

{
  "agents": [
    {
      "identifier": "alpaca-finance-expert",

If you see JSON output, congratulations — the toolkit is installed and working!

Step 5: Choose What to Do Next

The toolkit has many components. You don't need all of them. Pick the path that matches your goal:

Path A: "I want to connect AI to blockchains" (Most Popular)

This is the core use case. You'll start an MCP server and connect it to Claude Desktop.

Continue to: Your First MCP Server below.

Path B: "I want to use/explore AI agents"

You want to browse the 78 agents and use them with your AI assistant.

Continue to: Agents Guide — shows how to load agents into Claude, ChatGPT, or any LLM.

Path C: "I want live crypto market data"

You want real-time prices, news, and market analytics.

Continue to: Market Data Guide

Path D: "I want to sweep dust tokens"

You want to consolidate tiny token balances across chains.

Continue to: DeFi Tools Guide

Path E: "I just want to look around"

Start the frontend to explore:

bun run dev

Open http://localhost:5173 in your browser. You'll see the agent catalog with all 78 agents, their descriptions, and full configurations.

Your First MCP Server

This section walks you through starting the BNB Chain MCP server and connecting it to Claude Desktop. This gives Claude direct access to blockchain data.

5a. Install and Start the Server

cd mcp-servers/bnbchain-mcp
bun install
bun run build

Note: Each MCP server has its own dependencies, so you need to run bun install inside the server directory too.

5b. Connect to Claude Desktop

Claude Desktop reads MCP server configs from a JSON file. Find or create it:

OS	Config file location
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Add this to the file (create the file if it doesn't exist):

{
  "mcpServers": {
    "bnbchain": {
      "command": "npx",
      "args": ["-y", "@nirholas/bnbchain-mcp"],
      "env": {
        "BSC_RPC_URL": "https://bsc-dataseed.binance.org"
      }
    }
  }
}

5c. Restart Claude Desktop

Close and reopen Claude Desktop completely (not just the window — fully quit and relaunch).

5d. Try It Out

Open a new conversation in Claude and ask:

"What's the BNB balance of address 0xF977814e90dA44bFA03b6295A0616a897441aceC?"

If everything is working, Claude will call the MCP server, query the BSC blockchain, and return the real balance.

What just happened:

Your question → Claude → MCP Server → BSC Blockchain → Real data → Claude's answer

Claude didn't guess — it looked up the actual on-chain data.

What if Claude doesn't show MCP tools?

Is the config file valid JSON? Open it and check for typos (missing commas, extra brackets)
Did you fully restart Claude? On Mac: Cmd+Q, then reopen. On Windows: right-click tray icon → Quit
Is the server reachable? Open a separate terminal and check: npx -y @nirholas/bnbchain-mcp
Still stuck? See the Troubleshooting guide

Optional: Add API Keys for More Features

The basic setup works without any API keys, but adding them unlocks more capabilities:

API Key	What It Unlocks	How to Get One
`COINGECKO_API_KEY`	Higher rate limits for price data	coingecko.com/api (free tier available)
`BINANCE_API_KEY` + `BINANCE_SECRET_KEY`	Trading on Binance exchange	binance.com/en/my/settings/api-management
`PRIVATE_KEY`	On-chain write operations (sending tokens, swaps)	Export from your wallet (MetaMask → Account Details → Export Private Key)

Set them as environment variables:

# Linux/Mac
export COINGECKO_API_KEY="your-key-here"

# Or create a .env file
echo 'COINGECKO_API_KEY=your-key-here' >> .env

Security Warning: Never commit API keys or private keys to Git. The .gitignore file already excludes .env files, but always double-check.

Understanding the Project Structure

Now that everything is running, here's what each top-level folder does:

bnb-chain-toolkit/
├── agents/            ← 78 AI agent definitions (JSON files)
│   ├── bnb-chain-agents/  ← 36 agents for BNB Chain specifically
│   └── defi-agents/       ← 42 agents for general DeFi
├── mcp-servers/       ← 6 MCP servers (the core technology)
├── market-data/       ← Live crypto prices and news
├── defi-tools/        ← Dust sweeper utility
├── wallets/           ← Offline wallet toolkit
├── standards/         ← ERC-8004 and W3AG specs
├── docs/              ← You are here
├── src/               ← Agent source files (processed by build)
├── public/            ← Built output (index.json)
├── scripts/           ← Build tools
├── locales/           ← 30+ language translations
└── schema/            ← JSON Schema for validation

Deep dive: See Architecture for detailed diagrams and data flows.

Common First Steps After Setup

Goal	Command / Action
Browse all agents visually	`bun run dev` → open http://localhost:5173
Start the Binance MCP server too	`cd mcp-servers/binance-mcp && bun install`
Run tests to verify everything	`bun run test`
Check for linting issues	`bun run lint`
Format all JSON files	`bun run format`
Read real-world usage patterns	Examples

What's Next?

Guide	What You'll Learn
Architecture	How all the pieces fit together, with diagrams
Agents	Deep dive into all 78 agents, plus creating your own
MCP Servers	Setting up all 6 servers with configuration details
Examples	Real-world usage from beginner to advanced
FAQ	Answers to questions you'll probably have
Troubleshooting	When things go wrong
Glossary	Any term you don't recognize

Need Help?

Something not working? → Troubleshooting
Don't understand a term? → Glossary
Found a bug? → Open an issue
Want to contribute? → CONTRIBUTING.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Getting Started

Before You Start

What You'll Need

What You Won't Need (Yet)

Step 1: Download the Toolkit

Step 2: Install Dependencies

Step 3: Build the Agent Index

Step 4: Verify Everything Works

Step 5: Choose What to Do Next

Path A: "I want to connect AI to blockchains" (Most Popular)

Path B: "I want to use/explore AI agents"

Path C: "I want live crypto market data"

Path D: "I want to sweep dust tokens"

Path E: "I just want to look around"

Your First MCP Server

5a. Install and Start the Server

5b. Connect to Claude Desktop

5c. Restart Claude Desktop

5d. Try It Out

Optional: Add API Keys for More Features

Understanding the Project Structure

Common First Steps After Setup

What's Next?

Need Help?

Uh oh!

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

Getting Started

Before You Start

What You'll Need

What You Won't Need (Yet)

Step 1: Download the Toolkit

Step 2: Install Dependencies

Step 3: Build the Agent Index

Step 4: Verify Everything Works

Step 5: Choose What to Do Next

Path A: "I want to connect AI to blockchains" (Most Popular)

Path B: "I want to use/explore AI agents"

Path C: "I want live crypto market data"

Path D: "I want to sweep dust tokens"

Path E: "I just want to look around"

Your First MCP Server

5a. Install and Start the Server

5b. Connect to Claude Desktop

5c. Restart Claude Desktop

5d. Try It Out

Optional: Add API Keys for More Features

Understanding the Project Structure

Common First Steps After Setup

What's Next?

Need Help?