🚀 0xGasless MCP Server

🔗 Seamless Blockchain Integration for Claude AI

Execute gasless transactions, swaps, and transfers directly from your Claude conversations

🚀 Quick Start • 📖 Documentation • 🛠️ Development • 🤝 Contributing

</div>

---

🌟 What is 0xGasless MCP Server?

The 0xGasless MCP Server is a powerful Model Context Protocol 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:

# Global installation (recommended)
npm install -g 0xgasless-mcp

# Or use directly with npx
npx 0xgasless-mcp

⚙️ Configuration

1️⃣ Automatic Setup (Easiest)

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:

# 🔑 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:

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

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

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

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 file for details.

---

🙏 Acknowledgments

Special thanks to the amazing teams and projects that make this possible:

• 🎯 0xGasless - Smart account infrastructure
• 🤖 Model Context Protocol - MCP specification
• 🧠 Claude - AI integration capabilities
• 🌐 OpenRouter - AI API access platform

---

📚 Resources & Links

📖 Documentation

• 📘 0xGasless Documentation
• 📗 MCP Documentation
• 📙 Claude MCP Guide

🔗 Project Links

• 🏠 GitHub Repository
• 📦 npm Package
• 🐛 Report Issues
• 💬 Discussions

---

<div align="center">

🚀 Made with ❤️ for the blockchain community

Empowering AI-driven blockchain interactions

</div>