Tairon-ai/moduluszk-mcp

🚀 Features

⛓️ Blockchain Integration

• Full Modulus Testnet integration with ethers.js
• Chain ID: 6666 support with automatic network configuration
• Real-time transaction monitoring and confirmation
• Gas price estimation and optimization
• Direct explorer links for all transactions and addresses
• Automatic retry logic with exponential backoff

💎 Token Operations

• Native ETH balance checking and transfers
• ERC20 token support with full metadata retrieval
• Custom token creation and minting
• Multi-token balance queries in single call
• Token approval and allowance management
• Automatic decimal handling

🚿 Faucet Integration

• Direct integration with Modulus Testnet faucet
• Support for CULT, RVLT, and TRG test tokens
• Automatic faucet request handling
• Balance verification after faucet claims
• Rate limit management for faucet requests
• Queue system for multiple token requests

🔗 Explorer Integration

• Every response includes direct explorer URLs
• Transactions come with explorerUrl to Modulus Eye explorer
• Addresses include direct links to explorer pages
• Token contracts linked to token explorer pages
• Real-time transaction status tracking
• No extra API calls needed - links generated automatically

📊 Smart Features

• Intelligent fallback to environment variables
• Optional private key parameter for flexibility
• Automatic address validation
• Gas estimation before transaction execution
• Transaction receipt verification
• Comprehensive error handling with detailed messages

🏛️ Enterprise Architecture

• MCP 2024-11-05 protocol compliance
• Dual server architecture (HTTP + stdio)
• Docker containerization ready
• Production-tested components
• 8 specialized blockchain tools
• Environment-based configuration

📦 Quick Start

✅ Prerequisites

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

# For blockchain operations
Ethereum wallet with private key
Test ETH on Modulus Testnet

🔑 Configuration

The server requires minimal configuration:

• Private Key: Required for transaction signing
• Default Address: Optional, for read-only operations
• Network: Auto-configured for Modulus Testnet

📥 Installation

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

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your private key and settings

# Start the server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "moduluszk": {
      "command": "node",
      "args": ["/path/to/moduluszk-mcp/mcp-server/mcp/index.js"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "DEFAULT_ADDRESS": "your_ethereum_address",
        "RPC_URL": "https://rpc.moduluszk.io",
        "CHAIN_ID": "6666",
        "EXPLORER_URL": "https://eye.moduluszk.io"
      }
    }
  }
}

🛠 Available Tools

💰 Balance Tools

🚿 Faucet Tools

💸 Transfer Tools

🎨 Token Creation

📊 Analytics Tools

💡 Examples

💰 Check Balances

// Request
{
  "tool": "check_balances",
  "params": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "tokenAddresses": ["0xDD161001230a59F15F61b37EE997F77C15753E7c"]
  }
}

// Response includes
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "explorerUrl": "https://eye.moduluszk.io/address/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "balances": {
    "native": {
      "balance": "10.5",
      "symbol": "ETH"
    }
  }
}

🚿 Request Faucet

{
  "tool": "request_faucet",
  "params": {
    "tokenSymbol": "CULT"
  }
}

💸 Transfer Native ETH

{
  "tool": "transfer_native",
  "params": {
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "0.1"
  }
}

🪙 Transfer ERC20

{
  "tool": "transfer_erc20",
  "params": {
    "tokenAddress": "0xDD161001230a59F15F61b37EE997F77C15753E7c",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "100"
  }
}

🎨 Create Token

{
  "tool": "create_token",
  "params": {
    "name": "My Token",
    "symbol": "MTK",
    "totalSupply": "1000000",
    "decimals": 18
  }
}

📊 Get Transaction

{
  "tool": "get_transaction",
  "params": {
    "txHash": "0x123abc..."
  }
}

⛽ Get Gas Price

{
  "tool": "get_gas_price",
  "params": {}
}

📈 Estimate Gas

{
  "tool": "estimate_gas",
  "params": {
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "value": "0.1"
  }
}

🤖 Prompts

💬 Example Prompts for AI Assistants

💰 Balance Queries

"Check my balance"
"Show ETH balance for address 0x..."
"Get balance of CULT token"
"Check all token balances for wallet"
"Show my RVLT and TRG balances"
"What's my portfolio value?"
"Check native and ERC20 balances"
"Get all balances with explorer links"

🚿 Faucet Requests

"Request CULT tokens from faucet"
"Get test tokens"
"I need RVLT tokens"
"Request TRG from faucet"
"Get all faucet tokens"
"Request testnet funds"
"I need tokens for testing"
"Get CULT, RVLT and TRG tokens"

💸 Transfers

"Send 0.1 ETH to address 0x..."
"Transfer 100 CULT tokens"
"Send native tokens to wallet"
"Transfer ERC20 to address"
"Send all my RVLT tokens"
"Transfer with private key"
"Send tokens from my wallet"
"Execute batch transfers"

🎨 Token Creation

"Create new ERC20 token"
"Deploy token with 1M supply"
"Create My Token (MTK)"
"Mint new token with 18 decimals"
"Deploy custom token contract"
"Create token for testing"
"Deploy NFT collection token"
"Create governance token"

📊 Transaction Monitoring

"Check transaction status"
"Get tx details for hash 0x..."
"Show transaction on explorer"
"Is my transaction confirmed?"
"Get transaction receipt"
"Check pending transactions"
"Show gas used for tx"
"Get confirmation count"

⛽ Gas Management

"What's current gas price?"
"Estimate gas for transfer"
"Check gas cost in ETH"
"Get max fee per gas"
"Estimate transaction cost"
"Show gas price in gwei"
"Calculate total tx cost"
"Get priority fee"

🔗 Explorer Links

"Show address on explorer"
"Get explorer link for tx"
"View token on Modulus Eye"
"Open transaction in explorer"
"Get all explorer URLs"
"Show contract on explorer"
"View wallet history"
"Get blockchain explorer links"

🌐 Network Info

"What network am I on?"
"Show chain ID"
"Get RPC endpoint"
"Show network details"
"What's Modulus Testnet?"
"Get blockchain info"
"Show network status"
"Check if testnet is live"

💼 Advanced Operations

"Deploy and verify contract"
"Batch transfer to 10 addresses"
"Check allowance for spender"
"Approve token spending"
"Get nonce for address"
"Estimate gas for contract call"
"Send transaction with data"
"Call contract function"

🔒 Security Checks

"Validate ethereum address"
"Check if address is contract"
"Verify transaction signature"
"Is private key valid?"
"Check address checksum"
"Validate transaction hash"
"Verify contract deployment"
"Check if address has code"

🔒 Security

🛡️ Security Features

• Private Key Protection - Never logged or exposed
• Environment Variables - Secure credential storage
• Input Validation - All addresses and amounts validated
• Transaction Confirmation - Receipt verification
• Error Handling - Safe error messages without sensitive data
• Gas Limits - Automatic gas estimation and limits
• Checksum Validation - Address checksum verification

🔐 Best Practices

• Never share private keys - Keep them secure
• Use separate wallets - Different wallets for testing
• Monitor transactions - Check explorer regularly
• Verify addresses - Double-check before sending
• Test first - Use small amounts for testing
• Keep backups - Backup wallet seeds securely

🌐 Network Information

⛓️ Modulus Testnet

• Network Name: Modulus Testnet
• Chain ID: 6666
• RPC URL: https://rpc.moduluszk.io
• Explorer: https://eye.moduluszk.io
• Faucet: https://faucet.moduluszk.io
• Documentation: https://docs.moduluszk.io

🪙 Supported Tokens

⚡ Network Features

• Fast block times (~3 seconds)
• Low transaction fees
• EVM compatible
• Smart contract support
• Web3 wallet compatible
• Testnet faucet available

🚀 Deployment

🏭 Production Deployment

# With PM2
pm2 start server.js --name moduluszk-mcp

# With Docker
docker build -t moduluszk-mcp .
docker run -d -p 8080:8080 --env-file .env --name moduluszk-mcp moduluszk-mcp

# Using Docker Compose
docker-compose up -d

# With systemd
sudo systemctl start moduluszk-mcp

🔧 Environment Variables

# Network Configuration
RPC_URL=https://rpc.moduluszk.io
CHAIN_ID=6666
EXPLORER_URL=https://eye.moduluszk.io
FAUCET_URL=https://faucet.moduluszk.io

# Wallet Configuration
PRIVATE_KEY=your_private_key_here
DEFAULT_ADDRESS=your_ethereum_address

# Token Addresses
CULT_TOKEN_ADDRESS=0x0000000000000000000000000000000000000000
RVLT_TOKEN_ADDRESS=0xDD161001230a59F15F61b37EE997F77C15753E7c
TRG_TOKEN_ADDRESS=0xe99dc079Ce831DEe0097877D6B21796434125a04

# Server Configuration
PORT=8080
NODE_ENV=production

🐳 Docker Support

FROM node:lts-alpine
LABEL maintainer="Moduluszk Team <dev@moduluszk.io>"
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 8080
CMD ["node", "server.js"]

📈 Performance

• Response Time: <100ms for blockchain queries
• Gas Optimization: Automatic gas price optimization
• Rate Limiting: Built-in rate limit handling
• Connection Pooling: Optimized RPC connections
• Error Recovery: Automatic retry with exponential backoff
• Transaction Speed: ~3 second block times

🏗 Architecture

Project Structure

mcp-server/
├── server.js           # Express HTTP server
├── mcp/
│   ├── index.js       # MCP server implementation
│   └── tools.js       # Blockchain tools implementation
├── package.json        # Dependencies and scripts
├── .env.example       # Environment configuration template
├── Dockerfile         # Container configuration
├── docker-compose.yml # Multi-container orchestration
└── README.md          # Documentation

Components

HTTP Server (server.js)

• RESTful API endpoints
• MCP subprocess management
• Health monitoring
• CORS and JSON parsing

MCP Server (mcp/index.js)

• MCP protocol implementation
• Tool definitions and schemas
• Request handling
• stdio communication

Blockchain Tools (mcp/tools.js)

• Ethers.js integration
• Transaction management
• Token operations
• Gas estimation

🤝 Contributing

Contributions are welcome! Please see for guidelines.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Modulus Network - Blockchain infrastructure
• Model Context Protocol - MCP specification
• Ethers.js - Ethereum library
• Express.js - Web framework
• Node.js - Runtime environment

📚 Resources

• Modulus Documentation
• MCP Documentation
• Modulus Block Explorer
• Modulus Faucet
• Ethers.js Documentation
• GitHub Repository

⚠️ Disclaimer

This software is provided "as is", without warranty of any kind. Use at your own risk. Always verify transactions before signing and never share your private keys.