<div align="center">

🚀 Monad Testnet MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for Monad Testnet blockchain integration

Features • Quick Start • Tools • Examples • Prompts • Security

</div>

---

🚀 Features

⚡ Blockchain Integration

• Full Monad Testnet RPC integration with high-performance capabilities
• EVM-compatible smart contract interactions
• Real-time block and transaction monitoring
• Advanced gas estimation and optimization
• Native token and ERC-20 support
• Wallet generation and management
• Works without private keys - all read operations available via public RPC

🔗 Direct Access

• Every response includes relevant blockchain data
• Transactions include confirmations and gas details
• Blocks come with timestamp and transaction count
• Wallets provide balance in both wei and ether
• Token balances with proper decimal formatting
• Gas prices in real-time from the network
• No extra RPC calls needed - data aggregation built-in

📊 Block Management

• Get current block height
• Retrieve detailed block information
• Access block by number or hash
• Track block confirmations
• Monitor block production rate
• Historical block analysis

💎 Transaction Operations

• Submit and track transactions
• Get transaction receipts
• Monitor transaction status
• Estimate gas for transactions
• Access transaction logs
• Decode transaction data

👛 Wallet Management

• Generate new wallets securely
• Import wallets from mnemonic
• Check wallet balances
• View transaction count (nonce)
• Multi-wallet support
• HD wallet derivation

📈 Smart Contract Interactions

• Call contract read functions
• Estimate gas for contract calls
• Get contract bytecode
• Read contract storage
• Monitor contract events
• Decode contract data

🏛️ Enterprise-Ready Architecture

• Built with ethers.js v6 and Monad RPC
• Comprehensive error handling with fallback mechanisms
• Optimized for Monad's high throughput (10,000 TPS)
• Docker containerization support
• Production-tested components
• MCP protocol implementation
• 20+ specialized tools for blockchain operations
• Zero-configuration deployment (works with public RPC)

---

📦 Quick Start

Note: This MCP server provides full read-only access to Monad Testnet without requiring a private key. Authentication is only needed for write operations.

✅ Prerequisites

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

🔑 Configuration

Important: Private key is optional for read operations.

• Without Private Key: All read-only operations work with public RPC
• With Private Key: Enable transaction sending and contract interactions
• RPC Endpoint: Default Monad Testnet RPC is pre-configured
• Custom RPC: Set your own RPC for better performance

The server automatically detects configuration and adjusts capabilities accordingly.

📥 Installation

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

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env
# Edit .env only if you have custom RPC or private key

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

{
  "mcpServers": {
    "monad": {
      "command": "node",
      "args": ["/path/to/monad-mcp/mcp/index.js"],
      "env": {
        "MONAD_RPC_URL": "https://testnet-rpc.monad.xyz",
        "MONAD_API_KEY": "",  // Optional: Get API key at https://dashboard.blockvision.org
        "WALLET_PRIVATE_KEY": "",  // Optional: Leave empty for read-only
        "WALLET_ADDRESS": ""  // Optional: Your wallet address
      }
    }
  }
}

Note: For enhanced features and better performance, get your free API key at BlockVision Dashboard

---

🛠 Available Tools

📊 Blockchain Tools

Tool	Description	Parameters	Returns
get_block_number	Get current block height	None	Current block number
get_block	Get block details	blockNumber	Block data with transactions
get_transaction	Get transaction details	txHash	Transaction data
get_transaction_receipt	Get transaction receipt	txHash	Receipt with logs
get_gas_price	Get current gas price	None	Gas price in wei
get_network	Get network information	None	Chain ID and network details

💎 Account Tools

Tool	Description	Parameters	Returns
get_balance	Get wallet balance	address, blockTag	Balance in wei and ether
get_transaction_count	Get nonce for address	address, blockTag	Transaction count
get_code	Get contract bytecode	address, blockTag	Contract code
generate_wallet	Generate new wallet	None	Address and private key
generate_wallet_from_mnemonic	Import from mnemonic	mnemonic, path	Wallet details

👛 Token Tools

Tool	Description	Parameters	Returns
get_available_tokens	List known tokens	tag	Token list with details
get_token_info	Get token details	tokenAddress	Name, symbol, decimals
get_token_balance	Get token balance	tokenAddress, walletAddress	Token balance
get_account_tokens	Get all tokens for address	address	All token balances

🏪 Smart Contract Tools

Tool	Description	Parameters	Returns
call	Call contract function	to, data, from, blockTag	Function result
estimate_gas	Estimate gas for transaction	from, to, value, data	Gas estimate
get_logs	Get event logs	fromBlock, toBlock, address, topics	Event logs
get_storage_at	Read contract storage	address, slot, blockTag	Storage value

📈 Network Tools

Tool	Description	Parameters	Returns
get_fee_data	Get current fee data	None	Gas price, priority fee

---

💡 Examples

🎨 Get Current Block

// Request
{
  "tool": "get_block_number",
  "params": {}
}

// Response
{
  "blockNumber": 39454804,
  "network": "Monad Testnet"
}

📊 Get Block Details

{
  "tool": "get_block",
  "params": {
    "blockNumber": "39454804"
  }
}

💎 Check Balance

{
  "tool": "get_balance",
  "params": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}

👛 Get Transaction

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

🔥 Get Gas Price

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

📈 Estimate Gas

{
  "tool": "estimate_gas",
  "params": {
    "to": "0x...",
    "value": "1000000000000000000",
    "data": "0x"
  }
}

💰 Get Token Balance

{
  "tool": "get_token_balance",
  "params": {
    "tokenAddress": "0x...",
    "walletAddress": "0x..."
  }
}

🎯 Call Contract

{
  "tool": "call",
  "params": {
    "to": "0x...",
    "data": "0x...",
    "from": "0x..."
  }
}

🔍 Get Event Logs

{
  "tool": "get_logs",
  "params": {
    "fromBlock": "39000000",
    "toBlock": "latest",
    "address": "0x...",
    "topics": []
  }
}

---

🤖 Prompts

💬 Example Prompts for AI Assistants

🌍 Blockchain Queries

"What's the current block on Monad Testnet?"
"Show me details of block 39454804"
"Get the latest block information"
"How many transactions in the last block?"
"Show block production rate"
"Get block by hash"
"Find blocks with high transaction count"
"Show me blocks from last hour"
"Get block timestamp"
"Check block confirmations"

🎨 Transaction Management

"Get transaction details for hash 0x..."
"Show me transaction receipt"
"Check if transaction is confirmed"
"Get transaction logs"
"Decode transaction input data"
"Show gas used by transaction"
"Get transaction status"
"Find transactions from address"
"Show failed transactions"
"Get internal transactions"

🔗 Account Operations

"Check balance of address 0x..."
"Get my wallet balance"
"Show balance in ether"
"Get transaction count for address"
"Check nonce for wallet"
"Generate new wallet"
"Create wallet from mnemonic"
"Show all my wallets"
"Get wallet transaction history"
"Check if address is contract"

💰 Token Operations

"Show available tokens on Monad"
"Get USDC token balance"
"Check all tokens for address"
"Get token information"
"Show token decimals"
"List all stablecoins"
"Find governance tokens"
"Get token total supply"
"Show token holders"
"Check token allowance"

💸 Sending Transactions

"Send 0.1 MON to address 0x..."
"Transfer 100 USDC to 0x..."
"Send native tokens to wallet"
"Transfer ERC20 tokens"
"Send USDT using my private key"
"Transfer tokens with custom gas"
"Send transaction with specific nonce"
"Batch transfer to multiple addresses"
"Send all balance to address"
"Transfer NFT to wallet"

📊 Gas and Fees

"What's current gas price?"
"Estimate gas for transfer"
"Get priority fee"
"Show gas price in gwei"
"Calculate transaction cost"
"Get fee history"
"Optimize gas for transaction"
"Show base fee"
"Get max fee per gas"
"Check gas limit"

💎 Smart Contract Interactions

"Get contract code at address"
"Call read function on contract"
"Estimate gas for contract call"
"Get contract events"
"Read contract storage"
"Decode contract data"
"Get contract ABI"
"Verify contract source"
"Show contract creation tx"
"Get contract balance"

🔍 Event Logs

"Get Transfer events for token"
"Show events from block range"
"Filter events by topic"
"Get all events for address"
"Decode event data"
"Show event signatures"
"Get indexed parameters"
"Find specific event"
"Monitor events real-time"
"Get event history"

🚀 Network Information

"Show Monad network details"
"Get chain ID"
"Check network status"
"Show RPC endpoint"
"Get network version"
"Check if syncing"
"Show peer count"
"Get protocol version"
"Check network congestion"
"Show mempool status"

🎯 Wallet Generation

"Generate new wallet for me"
"Create wallet with mnemonic"
"Generate HD wallet"
"Create multiple wallets"
"Get wallet from private key"
"Derive wallet addresses"
"Generate vanity address"
"Create multisig wallet"
"Get wallet keystore"
"Export wallet"

🏆 Advanced Queries

"Get all transactions in last 100 blocks"
"Find contracts deployed today"
"Show high value transactions"
"Get MEV transactions"
"Find arbitrage opportunities"
"Show liquidity pools"
"Get staking rewards"
"Find token swaps"
"Show bridge transactions"
"Get protocol statistics"

💸 DeFi Operations

"Check DeFi protocols on Monad"
"Get lending rates"
"Show liquidity pools"
"Find yield farming options"
"Get swap quotes"
"Check collateral ratio"
"Show borrowed amount"
"Get LP token balance"
"Find flash loan providers"
"Check protocol TVL"

🎮 Development Helpers

"Deploy contract to Monad"
"Verify contract on explorer"
"Get contract creation code"
"Test contract function"
"Debug transaction failure"
"Simulate transaction"
"Get revert reason"
"Check contract size"
"Optimize contract gas"
"Test contract upgrade"

🌐 Cross-chain Queries

"Bridge assets to Monad"
"Check bridge status"
"Get wrapped token address"
"Show cross-chain messages"
"Verify bridge transaction"
"Get bridge fees"
"Check finality status"
"Show supported bridges"
"Get bridge limits"
"Track bridge volume"

📈 Analytics Queries

"Show Monad statistics"
"Get daily transaction count"
"Show unique addresses"
"Get average gas price"
"Show TPS metrics"
"Get block time average"
"Show network growth"
"Get active addresses"
"Show gas usage trends"
"Get protocol metrics"

---

🔒 Security

🛡️ Security Features

• Private Key Protection - Optional private key stored securely in environment variables
• RPC Security - Secure HTTPS connections to Monad RPC
• Input Validation - All inputs validated before processing
• Error Handling - Comprehensive error management with safe fallbacks
• Data Sanitization - Address and transaction data sanitized
• Read-Only Mode - Full functionality without private keys
• Safe Defaults - Conservative gas estimates and safe parameters

🔐 Best Practices

• Key Management: Never commit private keys
• RPC Selection: Use trusted RPC endpoints
• Gas Settings: Always estimate gas before transactions
• Address Validation: Verify addresses before sending
• Transaction Monitoring: Track transaction status
• Error Handling: Implement proper error recovery

---

📊 Supported Infrastructure

🌐 Network Details

• Network: Monad Testnet
  • RPC: https://testnet-rpc.monad.xyz
  • Chain ID: 41454
  • Block Time: ~1 second
  • Throughput: 10,000 TPS
  • EVM Compatible: Yes

📊 RPC Methods

• All standard Ethereum JSON-RPC methods
• Monad-optimized performance endpoints
• WebSocket support for real-time updates
• Batch request support

⚡ Performance

• Block Time: ~1 second
• Throughput: 10,000 TPS
• Finality: Single-slot finality
• Gas: Optimized for low cost

---

🚀 Deployment

🏭 Production Deployment

# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start mcp/index.js --name monad-mcp

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

🔑 Environment Variables

# Monad RPC Configuration
MONAD_RPC_URL=https://testnet-rpc.monad.xyz

# Wallet Configuration (Optional)
WALLET_ADDRESS=your_wallet_address  # Optional: For default wallet
WALLET_PRIVATE_KEY=your_private_key  # Optional: For write operations

# Server Configuration
PORT=8080
NODE_ENV=production

# Advanced Settings
MAX_BLOCK_RANGE=1000
DEFAULT_GAS_LIMIT=3000000
CONFIRMATION_BLOCKS=1

---

📈 Performance

• Response Time: <100ms for RPC queries
• Throughput: Supports Monad's 10,000 TPS
• Reliability: Automatic retry with exponential backoff
• Caching: Smart caching for frequently accessed data
• Concurrent Requests: Optimized for parallel operations
• Error Recovery: Graceful degradation and fallbacks

---

🎯 Key Features

✨ Real-time Blockchain Data

• Live block monitoring
• Transaction tracking
• Gas price updates
• Network statistics

🔄 Advanced Operations

• Smart contract interactions
• Token management
• Wallet operations
• Event monitoring

🛤️ EVM Compatibility

• Full Ethereum tooling support
• Solidity smart contracts
• Standard token interfaces
• Familiar development experience

---

🤝 Contributing

We welcome contributions!

# Fork the repository on GitHub, then clone
git clone https://github.com/Tairon-ai/monad-mcp

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

# Make changes and test
npm test

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

# Open Pull Request

---

📄 License

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

---

🙏 Acknowledgments

• Monad - High-performance EVM blockchain
• Ethers.js - Ethereum development library
• Model Context Protocol - AI integration standard
• Monad Community - Developer support

---

📚 Resources

• Monad Documentation
• Monad Testnet Faucet
• EVM Documentation
• Ethers.js Docs

---

📝 Network Information

Public Access (Default)

All tools in this MCP server work without authentication:

• ✅ Full read access to all blockchain data
• ✅ Block and transaction queries
• ✅ Balance and token checks
• ✅ Smart contract reads
• ✅ Event log queries

Authenticated Access (With Private Key)

With a configured private key:

• ✨ Send transactions
• ✨ Deploy contracts
• ✨ Token transfers
• ✨ Contract interactions
• ✨ Wallet management

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>