# 0G MCP Server 🚀

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![0G Network](https://img.shields.io/badge/0G-Network-blue)](https://0g.ai/)

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

```bash
# 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

```bash
# 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:

```json
{
  "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

| Tool | Description | Required Parameters | Optional Parameters |
|------|-------------|-------------------|--------------------|
| `get_balance` | Get wallet balance | `address` | `network` (mainnet/testnet) |
| `get_transaction` | Transaction details by hash | `txHash` | `network` |
| `get_block` | Block information | `blockIdentifier` | `network` |
| `get_network_info` | Network statistics | - | `network` |
| `estimate_gas` | Gas cost estimation | `to` | `value`, `data`, `network` |

## 💡 Usage Examples

### Development Mode
```bash
npm run dev
```

### Production Mode
```bash
npm start
```

### Manual Testing
```bash
# Test specific functionality
node test-server.js

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

## 🌐 Network Configuration

| Network | RPC Endpoint | Chain ID | Explorer |
|---------|--------------|----------|----------|
| **Mainnet** | `https://evmrpc-mainnet.0g.ai` | TBD | [chainscan.0g.ai](https://chainscan.0g.ai) |
| **Testnet** | `https://evmrpc-testnet.0g.ai` | TBD | [chainscan.0g.ai](https://chainscan.0g.ai) |

## 🔧 Advanced Configuration

### Environment Variables

Create a `.env` file for custom configuration:

```env
# 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

```typescript
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:

```bash
# 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 [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# 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](https://docs.0g.ai/)
- 🌐 [0G Website](https://0g.ai/)
- 💬 [Community Discord](https://discord.gg/0g)
- 🐦 [Twitter](https://twitter.com/0G_labs)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/yourusername/0g-mcp-server/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/yourusername/0g-mcp-server/discussions)
- 📧 **Email**: support@yourproject.com

---

<div align="center">
  <strong>Built with ❤️ for the 0G ecosystem</strong><br>
  <sub>Empowering AI agents with blockchain capabilities</sub>
</div>