<div align="center">

🔗 0G Chain MCP Server v0.1.0

Production-ready Model Context Protocol (MCP) server for 0G Chain blockchain operations

Features • Quick Start • Tools • Prompts • Security • Contributing

</div>

---

🚀 Features

⛓️ 0G Chain Integration

• Native 0G token operations (send, balance checks)
• Staking and delegation management
• Validator discovery and analytics
• Rewards tracking with auto-compounding support
• Ethereum-compatible wallet generation
• Direct interaction with 0G Chain Mainnet

🏗️ Dual-Server Architecture

• HTTP server (Express) for REST API access
• MCP stdio server for Claude Desktop integration
• Seamless communication between both servers
• Process management with graceful shutdown
• Health monitoring endpoints

🛠️ Professional Structure

• Modular tool system with separate tools.js
• Utility helpers in dedicated utils.js file
• Clean separation of concerns
• Easy to extend and maintain
• Production-tested components

🔧 Developer-Friendly

• Simple JSON-RPC interface
• Comprehensive error handling
• Environment-based configuration
• Docker containerization support
• MCP protocol 2024-11-05 implementation
• Zero-configuration deployment with sensible defaults

🎯 9 Powerful Tools

• Wallet creation and management
• Balance checks and token transfers
• Staking/unstaking operations
• Validator information and discovery
• Rewards tracking and calculations
• Explorer integration

---

📦 Quick Start

✅ Prerequisites

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

🔑 Configuration

Create a .env file in the project root (optional - defaults to 0G Mainnet):

# 0G Chain Configuration (defaults to Mainnet if not specified)
OG_RPC_URL=https://evmrpc.0g.ai
OG_CHAIN_ID=16661

# Wallet Configuration (required for transactions)
WALLET_PRIVATE_KEY=your_private_key_here
WALLET_ADDRESS=your_wallet_address_here

# HTTP Server Configuration
PORT=8080

Note: WALLET_PRIVATE_KEY and WALLET_ADDRESS are only required for transaction operations (send, stake, unstake). Read-only operations work without them.

📥 Installation

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

# Install dependencies
npm install

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

# Start the HTTP server
npm start

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

To configure the MCP server in Claude Desktop:

1. Open Claude Desktop application
2. Click on Settings (gear icon)
3. Navigate to Developer tab
4. Click Edit Config button
5. Add the following configuration to your MCP servers:

{
  "mcpServers": {
    "0g-chain": {
      "command": "node",
      "args": ["/absolute/path/to/0g-chain-mcp/mcp/index.js"],
      "env": {
        "OG_RPC_URL": "https://evmrpc.0g.ai",
        "OG_CHAIN_ID": "16661",
        "WALLET_PRIVATE_KEY": "your_private_key_here",
        "WALLET_ADDRESS": "your_wallet_address_here"
      }
    }
  }
}

6. Save the configuration and restart Claude Desktop

Security Note: Only add WALLET_PRIVATE_KEY if you plan to perform transactions through Claude. For read-only operations, you can omit it.

---

🛠 Available Tools

🔐 Wallet Management

Tool	Description	Parameters	Returns
create_wallet	Generate new 0G Chain wallet	None	Address, private key, mnemonic phrase

💰 Balance & Transfers

Tool	Description	Parameters	Returns
get_balance	Check 0G token balance	address (optional)	Balance in 0G and wei
send_native_token	Send 0G tokens	to_address, amount, from_private_key (optional), gas_limit (optional)	Transaction hash, explorer link

🎯 Staking Operations

Tool	Description	Parameters	Returns
stake_tokens	Delegate tokens to validator	validator_pubkey (address or pubkey), amount, delegator_private_key (optional)	Transaction hash, validator info, estimated rewards
unstake_tokens	Undelegate tokens from validator	validator_pubkey, amount (or "all"), withdrawal_address (optional), delegator_private_key (optional)	Transaction hash, shares burned, unbonding details
get_staking_info	Get delegation details	validator_pubkey, delegator_address (optional)	Current stake, shares, rewards estimates
get_accumulated_rewards	View accumulated rewards	validator_pubkey, delegator_address (optional), original_stake_amount (optional)	Current stake value, accumulated rewards, future estimates

📊 Validator Discovery

Tool	Description	Parameters	Returns
get_validators_list	List known validators	include_details (optional, boolean)	Validator addresses, names, optional on-chain details
get_validator_info	Detailed validator analytics	validator_pubkey (address or pubkey)	Complete validator metrics, commission, rewards, calculations

---

🤖 Prompts

💬 Example Prompts for Claude

Wallet Operations

"Create a new 0G Chain wallet for me"
"Check my 0G balance"
"What's the balance of address 0x..."
"Send 10 0G tokens to 0x..."

Staking Operations

"Show me all available 0G validators"
"Get detailed information about validator 0x..."
"Stake 1 0G token to validator 0x..."
"What are my accumulated rewards from validator 0x...?"
"Unstake 0.5 0G from validator 0x..."
"Unstake all my tokens from validator 0x..."

Analytics & Research

"Compare all validators and their commission rates"
"Which validator has the best APY?"
"How much would I earn staking 10 0G for a year?"
"Show me my current staking positions"
"Calculate my rewards if I originally staked 5 0G"

🌐 HTTP API Testing

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Check balance
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_balance", "arguments": {}}, "id": 1}'

# Get validators list
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_validators_list", "arguments": {"include_details": false}}, "id": 1}'

---

🔒 Security

🛡️ Security Best Practices

• Private Key Protection - Never commit .env files or private keys to Git
• Environment Variables - Store sensitive data (private keys) in environment variables only
• Read-Only by Default - Most tools work without private keys for maximum security
• Input Validation - All addresses and amounts are validated before processing
• Error Handling - Errors don't expose sensitive information
• Secure RPC - Uses HTTPS for all blockchain communication
• Explorer Integration - Verify all transactions on 0G Chain explorer

⚠️ Important Notes

• 21-Day Unbonding Period: Unstaked tokens are locked for 21 days before withdrawal
• Auto-Compounding Rewards: Rewards automatically compound into your stake (no separate claim needed)
• Withdrawal Fee: Small fee charged when unstaking (set by validator)
• Commission Rates: Validators charge commission on staking rewards (typically 5-10%)
• Gas Fees: All transactions require 0G tokens for gas fees

---

🚀 Deployment

🏭 Production Deployment

# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start server.js --name 0g-chain-mcp

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

🔑 Environment Variables

# 0G Chain Network Configuration
OG_RPC_URL=https://evmrpc.0g.ai
OG_CHAIN_ID=16661

# Wallet Configuration (optional for read-only operations)
WALLET_PRIVATE_KEY=your_private_key_here
WALLET_ADDRESS=your_wallet_address_here

# Server Configuration
PORT=8080
NODE_ENV=production

# Advanced Settings (optional)
RATE_LIMIT_REQUESTS_PER_SECOND=10

---

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for details on our development process.

# Fork the repository
git clone https://github.com/Tairon-ai/0g-chain-mcp.git

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

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

# Open Pull Request

---

📊 0G Chain Information

🌐 Network Details

• Network Name: 0G Chain Mainnet
• Chain ID: 16661
• RPC URL: https://evmrpc.0g.ai
• Explorer: https://explorer.0g.ai/mainnet
• Chain Scanner: https://chainscan.0g.ai
• Staking Contract: 0xea224dBB52F57752044c0C86aD50930091F561B9

---

📄 License

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

---

📚 Resources

• MCP Protocol Specification
• MCP GitHub Repository
• 0G Chain Documentation
• ethers.js Documentation
• Express.js Documentation

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>