Content
<div align="center">
# 🚀 Monad Testnet MCP Server v0.1
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://monad.xyz)
[](https://ethereum.org)
[](https://modelcontextprotocol.io)
[](https://www.docker.com)
**Production-ready Model Context Protocol (MCP) server for
Monad Testnet blockchain integration**
[Features](#-features) • [Quick Start](#-quick-start) • [Tools](#-available-tools) • [Examples](#-examples) • [Prompts](#-prompts) • [Security](#-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
```bash
# 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
```bash
# 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:
```json
{
"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](https://dashboard.blockvision.org)
---
## 🛠 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
```javascript
// Request
{
"tool": "get_block_number",
"params": {}
}
// Response
{
"blockNumber": 39454804,
"network": "Monad Testnet"
}
```
### 📊 Get Block Details
```javascript
{
"tool": "get_block",
"params": {
"blockNumber": "39454804"
}
}
```
### 💎 Check Balance
```javascript
{
"tool": "get_balance",
"params": {
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}
}
```
### 👛 Get Transaction
```javascript
{
"tool": "get_transaction",
"params": {
"txHash": "0x..."
}
}
```
### 🔥 Get Gas Price
```javascript
{
"tool": "get_gas_price",
"params": {}
}
```
### 📈 Estimate Gas
```javascript
{
"tool": "estimate_gas",
"params": {
"to": "0x...",
"value": "1000000000000000000",
"data": "0x"
}
}
```
### 💰 Get Token Balance
```javascript
{
"tool": "get_token_balance",
"params": {
"tokenAddress": "0x...",
"walletAddress": "0x..."
}
}
```
### 🎯 Call Contract
```javascript
{
"tool": "call",
"params": {
"to": "0x...",
"data": "0x...",
"from": "0x..."
}
}
```
### 🔍 Get Event Logs
```javascript
{
"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
```bash
# 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
```env
# 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!
```bash
# 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](LICENSE) file for details.
---
## 🙏 Acknowledgments
- [Monad](https://monad.xyz) - High-performance EVM blockchain
- [Ethers.js](https://docs.ethers.io/) - Ethereum development library
- [Model Context Protocol](https://modelcontextprotocol.io) - AI integration standard
- [Monad Community](https://discord.gg/monad) - Developer support
---
## 📚 Resources
- [Monad Documentation](https://docs.monad.xyz)
- [Monad Testnet Faucet](https://faucet.monad.xyz)
- [EVM Documentation](https://ethereum.org/developers)
- [Ethers.js Docs](https://docs.ethers.io)
---
## 📝 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](https://tairon.ai/) team with help from Claude**
</div>
