colygon/0g-mcp-server

0G MCP Server 🚀

A Model Context Protocol (MCP) server for seamless AI agent integration with the 0G blockchain network. This server enables AI assistants to query blockchain data, check balances, retrieve transactions, and perform blockchain operations through natural language.

🌟 Tested and Production Ready - Successfully connects to live 0G testnet with real-time data

✨ Features

• 🔍 Balance Queries - Check wallet balances on 0G mainnet/testnet
• 📊 Transaction Lookup - Get detailed transaction information by hash
• 🧱 Block Information - Retrieve block details by number or hash
• 📈 Network Statistics - Live gas prices and network metrics
• ⛽ Gas Estimation - Calculate transaction costs
• 🌐 Multi-network Support - Seamless mainnet/testnet switching
• 🤖 AI-First Design - Built specifically for AI agent interactions

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• An MCP-compatible client (Claude Desktop, etc.)

1. Installation

# Clone the repository
git clone https://github.com/yourusername/0g-mcp-server.git
cd 0g-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

2. Test the Server

# Run the test suite
node test-server.js

# Expected output:
# ✅ Server initialization successful
# ✅ All 5 blockchain tools registered
# ✅ Live connection to 0G testnet confirmed

3. Configure Your MCP Client

For Claude Desktop:

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the 0G MCP server:

{
  "mcpServers": {
    "0g-blockchain": {
      "command": "node",
      "args": ["/full/path/to/0g-mcp-server/dist/index.js"]
    }
  }
}

3. Restart Claude Desktop

For Other MCP Clients:

Refer to your client's documentation for MCP server configuration.

4. Start Using!

Once configured, you can interact with the 0G blockchain through natural language:

"Check the balance of address 0x1234... on 0G testnet"
"Get details for transaction 0xabcd... on 0G mainnet"
"What's the current gas price on 0G network?"
"Show me block 4259504 information"

🛠️ Available Tools

💡 Usage Examples

Development Mode

npm run dev

Production Mode

npm start

Manual Testing

# Test specific functionality
node test-server.js

# Check server health
curl -X POST http://localhost:3000/health

🌐 Network Configuration

🔧 Advanced Configuration

Environment Variables

Create a .env file for custom configuration:

# Custom RPC endpoints (optional)
ZG_MAINNET_RPC=https://your-custom-mainnet-rpc.com
ZG_TESTNET_RPC=https://your-custom-testnet-rpc.com

# Default network
DEFAULT_NETWORK=testnet

# Request timeout (ms)
REQUEST_TIMEOUT=30000

Custom Client Integration

import { ZGMCPServer } from './src/index.js';

const server = new ZGMCPServer({
  defaultNetwork: 'mainnet',
  customRpcEndpoints: {
    mainnet: 'https://your-rpc.com',
    testnet: 'https://your-testnet-rpc.com'
  }
});

await server.run();

🧪 Testing

The server includes comprehensive testing:

# Run all tests
npm test

# Test specific functionality
node test-server.js

# Test with live network
npm run test:live

Test Coverage:

• ✅ MCP protocol compliance
• ✅ All blockchain tools
• ✅ Network connectivity
• ✅ Error handling
• ✅ Live data retrieval

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Fork and clone the repo
git clone https://github.com/yourusername/0g-mcp-server.git

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

📚 About 0G Network

0G is a modular AI-first blockchain that revolutionizes decentralized AI:

• 🧠 AI-Optimized Storage - Ultra-low cost data storage for AI models
• ⚡ High-Performance Execution - Scalable compute for AI workloads
• 🔒 Trustless AI Inference - Cryptographically verifiable AI operations
• 🏗️ Modular Architecture - Pick only the components you need

Learn More:

• 📖 Official Documentation
• 🌐 0G Website
• 💬 Community Discord
• 🐦 Twitter

📄 License

MIT License - see file for details.

🆘 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: support@yourproject.com