Content
# 🚀 0xGasless MCP Server
**🔗 Seamless Blockchain Integration for Claude AI**
*Execute gasless transactions, swaps, and transfers directly from your Claude conversations*
[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [🛠️ Development](#️-development) • [🤝 Contributing](#-contributing)
</div>
---
## 🌟 What is 0xGasless MCP Server?
The **0xGasless MCP Server** is a powerful [Model Context Protocol](https://modelcontextprotocol.io) server that bridges Claude AI with blockchain networks. Built on **ERC-4337 Account Abstraction**, it enables gasless blockchain operations through natural language conversations.
### ✨ Key Highlights
- 🆓 **Zero Gas Fees** - Execute transactions without holding native tokens
- 🌐 **Multi-Chain Support** - 8+ blockchain networks supported
- 🤖 **AI-Native** - Natural language blockchain interactions
- 🔒 **Secure** - Smart account abstraction with enhanced security
- ⚡ **Instant Setup** - One-command Claude integration
---
## 🛠️ Available Tools
| Tool | Description | Example Usage |
|------|-------------|---------------|
| 🏠 `get-address` | Retrieve your smart account address | *"What's my wallet address?"* |
| 💰 `get-balance` | Check token balances (ERC20 support) | *"Show my USDC balance"* |
| 📤 `transfer-token` | Send tokens gaslessly | *"Send 10 USDT to alice.eth"* |
| 🔄 `swap-tokens` | Exchange tokens without gas | *"Swap 100 USDT for USDC"* |
| 🎯 `buy-openrouter-credits` | Purchase AI credits with USDC | *"Buy $25 OpenRouter credits"* |
---
## 🚀 Quick Start
### 📦 Installation
Choose your preferred installation method:
```bash
# Global installation (recommended)
npm install -g 0xgasless-mcp
# Or use directly with npx
npx 0xgasless-mcp
```
### ⚙️ Configuration
#### 1️⃣ Automatic Setup (Easiest)
```bash
0xgasless-mcp configure
```
This interactive command will:
- ✅ Collect your API keys and configuration
- ✅ Detect your operating system
- ✅ Configure Claude Desktop automatically
- ✅ Validate all inputs
#### 2️⃣ Manual Environment Setup
Create a `.env` file with your configuration:
```bash
# 🔑 Required Configuration
PRIVATE_KEY=0x... # Your wallet private key
RPC_URL=https://... # Blockchain RPC endpoint
API_KEY=your_0xgasless_api_key # From dashboard.0xgasless.com
CHAIN_ID=56 # Target blockchain (see table below)
# 🎯 Optional Configuration
OPENROUTER_API_KEY=your_key # For AI credit purchases
```
---
## 🌐 Supported Networks
| 🌍 Network | 🆔 Chain ID | 💎 Native Token | 🔗 RPC Endpoint |
|------------|-------------|-----------------|------------------|
| 🟡 **BSC** | `56` | BNB | `https://bsc-dataseed.binance.org/` |
| 🔵 **Base** | `8453` | ETH | `https://mainnet.base.org` |
| ⚫ **Ethereum** | `1` | ETH | `https://eth.llamarpc.com` |
| 🟣 **Polygon** | `137` | MATIC | `https://polygon-rpc.com` |
| 🔴 **Avalanche** | `43114` | AVAX | `https://api.avax.network/ext/bc/C/rpc` |
| 🔵 **Fantom** | `250` | FTM | `https://rpc.ftm.tools` |
| 🌙 **Moonbeam** | `1284` | GLMR | `https://rpc.api.moonbeam.network` |
| 🟢 **Metis** | `1088` | METIS | `https://andromeda.metis.io/?owner=1088` |
---
## 🔗 Claude Desktop Integration
### 🎯 Automatic Configuration
The easiest way to integrate with Claude Desktop:
```bash
0xgasless-mcp configure
```
### 📝 Manual Configuration
Add to your Claude Desktop configuration file:
**📍 Configuration Locations:**
- 🍎 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- 🪟 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- 🐧 **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"0xgasless": {
"command": "npx",
"args": ["0xgasless-mcp-server"],
"env": {
"PRIVATE_KEY": "0x...",
"RPC_URL": "https://...",
"API_KEY": "your_0xgasless_api_key",
"CHAIN_ID": "56",
"OPENROUTER_API_KEY": "your_openrouter_key"
}
}
}
}
```
---
## 💬 Usage Examples
Once configured, interact with blockchain using natural language:
### 💰 Balance Inquiries
```
💬 "What's my wallet balance?"
💬 "Check my USDC balance on BSC"
💬 "Show all my token balances"
```
### 📤 Token Transfers
```
💬 "Send 10 USDT to 0x742d35Cc6634C0532925a3b8D4C9db96590b5c8e"
💬 "Transfer 0.1 BNB to alice.eth"
💬 "Send 50 USDC to my friend's wallet"
```
### 🔄 Token Swaps
```
💬 "Swap 100 USDT for USDC"
💬 "Exchange 0.5 BNB to WETH"
💬 "Convert 1000 BUSD to BNB"
```
### 🎯 AI Credit Purchases
```
💬 "Buy $10 worth of OpenRouter credits"
💬 "Purchase $25 OpenRouter credits with USDC"
```
---
## 🔑 API Keys Setup
### 🎯 0xGasless API Key
1. 🌐 Visit [0xGasless Dashboard](https://dashboard.0xgasless.com)
2. 📝 Create an account and new project
3. 🔑 Copy your API key
4. 💳 Add credits to your account
### 🤖 OpenRouter API Key (Optional)
1. 🌐 Visit [OpenRouter.ai](https://openrouter.ai)
2. 📝 Sign up and navigate to API Keys
3. 🔑 Generate a new API key
4. 💰 Add credits for AI model access
---
## 🛠️ Development
### 🏗️ Local Development Setup
```bash
# Clone the repository
git clone https://github.com/achiit/0xgasless-mcp-server.git
cd 0xgasless-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Development mode with hot reload
npm run dev
# Start the server
npm start
```
### 📁 Project Structure
```
src/
├── 🎯 main.ts # Core MCP server implementation
├── 🚀 index.ts # CLI entry point & configuration
├── 📋 version.ts # Version management
└── 📝 types/ # TypeScript definitions
```
---
## 🔐 Security & Best Practices
### 🛡️ Security Guidelines
- 🔒 **Private Keys**: Store securely in environment variables, never in code
- 🔑 **API Keys**: Keep 0xGasless and OpenRouter keys confidential
- 🏦 **Smart Accounts**: Enhanced security through account abstraction
- ⛽ **Gasless Operations**: No native tokens required for transactions
### ⚠️ Important Notes
- 🚫 Never share your private key with anyone
- 💾 Use environment variables for sensitive data
- 🔄 Regularly rotate your API keys
- 📊 Monitor your account usage and credits
---
## 🆘 Troubleshooting
### 🐛 Common Issues & Solutions
<details>
<summary>🔴 "Chain ID not supported"</summary>
**Solution:**
- ✅ Verify you're using a supported chain ID from the table above
- ✅ Check the [supported networks](#-supported-networks) section
</details>
<details>
<summary>🔴 "API Key invalid"</summary>
**Solution:**
- ✅ Verify your 0xGasless API key is correct
- ✅ Ensure sufficient credits in your 0xGasless account
- ✅ Check API key permissions and expiration
</details>
<details>
<summary>🔴 "Insufficient balance"</summary>
**Solution:**
- ✅ Check token balance before operations
- ✅ Ensure you have enough tokens for the transaction
- ✅ Verify token contract address is correct
</details>
<details>
<summary>🔴 "Private key format error"</summary>
**Solution:**
- ✅ Ensure private key starts with "0x"
- ✅ Verify it's exactly 66 characters (64 + "0x")
- ✅ Check for any extra spaces or characters
</details>
### 🔍 Debug Mode
Enable detailed logging for troubleshooting:
```bash
DEBUG=1 0xgasless-mcp-server
```
---
## 🤝 Contributing
We welcome contributions! Here's how to get started:
### 🚀 Quick Contribution Guide
1. 🍴 **Fork** the repository
2. 🌿 **Create** a feature branch: `git checkout -b feature/amazing-feature`
3. 💾 **Commit** your changes: `git commit -m 'Add amazing feature'`
4. 📤 **Push** to branch: `git push origin feature/amazing-feature`
5. 🔄 **Open** a Pull Request
### 📋 Development Guidelines
- ✅ Follow TypeScript best practices
- ✅ Add tests for new features
- ✅ Update documentation as needed
- ✅ Ensure all tests pass before submitting
---
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
Special thanks to the amazing teams and projects that make this possible:
- 🎯 **[0xGasless](https://0xgasless.com)** - Smart account infrastructure
- 🤖 **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP specification
- 🧠 **[Claude](https://claude.ai)** - AI integration capabilities
- 🌐 **[OpenRouter](https://openrouter.ai)** - AI API access platform
---
## 📚 Resources & Links
### 📖 Documentation
- 📘 [0xGasless Documentation](https://docs.0xgasless.com)
- 📗 [MCP Documentation](https://modelcontextprotocol.io/docs)
- 📙 [Claude MCP Guide](https://docs.anthropic.com/claude/docs/mcp)
### 🔗 Project Links
- 🏠 [GitHub Repository](https://github.com/achiit/0xgasless-mcp-server)
- 📦 [npm Package](https://www.npmjs.com/package/0xgasless-mcp)
- 🐛 [Report Issues](https://github.com/achiit/0xgasless-mcp-server/issues)
- 💬 [Discussions](https://github.com/achiit/0xgasless-mcp-server/discussions)
---
<div align="center">
**🚀 Made with ❤️ for the blockchain community**
*Empowering AI-driven blockchain interactions*
[](https://github.com/achiit)
[](https://github.com/achiit/0xgasless-mcp-server)
</div>
