🌐 Plasma Testnet MCP Server v0.1
Production-ready Model Context Protocol (MCP) server for Plasma Testnet
Features • Quick Start • API • Tools • Examples • Prompts • Security
🚀 Features
🎯 Complete Blockchain Integration
- Full Plasma Network testnet support with native XPL token operations
- Real-time transaction monitoring and status tracking
- Gas estimation and optimization for cost-effective operations
- Multi-signature wallet support (coming soon)
- Smart contract interaction capabilities
- Comprehensive block explorer integration
🧠 Intelligent Transaction Engine
- Automatic gas price calculation and optimization
- Transaction simulation before execution
- Nonce management and conflict resolution
- Error recovery with automatic retry logic
- Transaction receipt confirmation
- Real-time network status monitoring
🤖 MCP Protocol Implementation
- 14+ specialized tools for blockchain automation
- Compatible with Claude Desktop and AI assistants
- HTTP and stdio transport support
- Zod schema validation for all parameters
- Comprehensive error handling and logging
- Production-tested components
🏛️ Enterprise-Ready Architecture
- Built with Express.js for scalability
- Ethers.js v5 for blockchain interactions
- Full TypeScript type safety (via Zod)
- Docker containerization support
- Comprehensive logging and monitoring
- Environment-based configuration
📦 Quick Start
✅ Prerequisites
# Required
Node.js >= 18.0.0
npm >= 9.0.0
# Optional
Docker & Docker Compose (for containerized deployment)
Private key for transaction execution
📥 Installation
# Clone the repository
git clone https://github.com/tairon-ai/plasma-mcp.git
cd plasma-mcp
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your configuration
# Start the server
npm start
# Development mode
npm run dev
# MCP stdio server for Claude Desktop
npm run mcp
🐳 Docker Deployment
# Build and run with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
🤖 Claude Desktop Integration
Add to your Claude Desktop configuration:
{
"mcpServers": {
"plasma-network": {
"command": "node",
"args": ["/path/to/plasma-mcp/mcp/index.js"],
"env": {
"RPC_URL": "https://testnet-rpc.plasma.to",
"WALLET_PRIVATE_KEY": "your_private_key_without_0x"
}
}
}
}
🛠 Available Tools
🏦 Blockchain Operations
| Tool | Description | Parameters |
|---|---|---|
getServiceInfo | Get server capabilities and config | - |
getNetworkInfo | Get Plasma network information | - |
getAccountBalance | Get XPL balance for address | address (optional) |
sendTransaction | Send custom transaction | to, value, data, gasLimit, gasPrice |
sendXPL | Send XPL tokens | to, amount |
getTransactionStatus | Check transaction status | txHash |
requestFaucet | Get testnet faucet info | address, faucetName |
estimateGas | Estimate gas for transaction | from, to, value, data |
getLatestBlocks | Get recent blocks | count |
getGasPrice | Get current gas price | - |
getTokenInfo | Get token details | tokenAddress |
getWalletBalances | Get wallet token balances | walletAddress, tokens |
🔗 API Endpoints
🌐 Core Endpoints
GET / # Server status and info
GET /health # Health check
GET /info # Service information
GET /mcp # MCP server information
POST /mcp # MCP protocol endpoint
💡 Examples
💰 Get Account Balance
// Get XPL balance
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "getAccountBalance",
"arguments": {
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9"
}
},
"id": 1
}
🔄 Send XPL Tokens
// Send 10 XPL to address
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "sendXPL",
"arguments": {
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9",
"amount": "10.0"
}
},
"id": 1
}
📊 Check Transaction Status
// Check transaction by hash
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "getTransactionStatus",
"arguments": {
"txHash": "0x123...abc"
}
},
"id": 1
}
🤖 Prompts
💬 Example Prompts for Claude, ChatGPT, or Other AI Assistants
These prompts demonstrate how to interact with the MCP server through natural language when integrated with AI assistants:
💱 Token Operations
"What's my XPL balance?"
"Send 5 XPL to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9"
"Check the status of transaction 0x123...abc"
"Estimate gas for sending 100 XPL to this address"
📊 Network Analysis
"Show me the current gas price on Plasma Network"
"Get the latest 5 blocks from the network"
"What's the current network status?"
"Show me network information including block height"
💼 Wallet Management
"Get my wallet nonce and balance"
"Show all token balances in my wallet"
"Request testnet XPL from the faucet"
"Calculate the cost of a transaction with current gas prices"
🔧 Smart Contract Interaction
"Get information about token at address 0x..."
"Send a custom transaction with data payload"
"Estimate gas for a contract interaction"
"Check if a transaction was successful"
🔧 Integration Tips for AI Assistants
When using these prompts with the MCP server:
- Always specify addresses in full format (0x...)
- Use decimal amounts for XPL (e.g., "10.5" not "10500000000000000000")
- Check gas prices before large transactions
- Verify balances before attempting transfers
- Monitor transaction status after sending
🧪 Testing
🔍 API Testing with cURL
# Check server health
curl http://localhost:8080/health
# Get MCP server info
curl http://localhost:8080/mcp
# Get service information
curl http://localhost:8080/info
# Execute a tool
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "getNetworkInfo",
"arguments": {}
},
"id": 1
}'
🔒 Security
🔐 Best Practices
- Private Key Management: Never commit private keys. Use environment variables
- Transaction Validation: All parameters are validated with Zod schemas
- Gas Limits: Automatic gas estimation with safety margins
- Error Handling: Comprehensive error handling for all operations
- Access Control: Implement authentication for production deployments
- Monitoring: Use block explorer to track all transactions
🛡️ Security Features
- Zod schema validation for all inputs
- Automatic gas estimation with buffer
- Transaction simulation capabilities
- Private key encryption support
- Rate limiting ready
- Comprehensive audit logging
📊 Supported Networks & Tokens
🌐 Network
- Plasma Testnet (Chain ID: 9746)
- RPC:
https://testnet-rpc.plasma.to - Explorer: Plasma Explorer
🪙 Native Token
- XPL: Native Plasma Network token
- Decimals: 18
- Used for gas fees and transfers
📜 Future Contracts (Pending Deployment)
- DEX Router: Decentralized exchange routing
- Token Factory: ERC20 token deployment
- Liquidity Pools: Automated market making
🚀 Deployment
🏭 Production Deployment
# Build for production
npm run build
# Start production server
NODE_ENV=production npm start
# With PM2
pm2 start server.js --name plasma-mcp
# With Docker
docker build -t plasma-mcp .
docker run -d -p 8080:8080 --env-file .env plasma-mcp
🔑 Environment Variables
# Required for transactions
WALLET_PRIVATE_KEY=your_private_key_without_0x
# Network configuration
RPC_URL=https://testnet-rpc.plasma.to
# Optional
PORT=8080
NODE_ENV=production
📈 Performance
- Response Time: <100ms for read operations
- Transaction Speed: ~2-5s on Plasma Network
- Throughput: 100+ requests per second
- Gas Optimization: Automatic gas price calculation
- Caching: Optimized for repeated queries
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
# Fork and clone
git fork https://github.com/tairon-ai/plasma-mcp
git clone https://github.com/tairon-ai/plasma-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
- Plasma Network - Next-generation blockchain platform
- Model Context Protocol - AI integration standard
- Ethers.js - Ethereum library
- Anthropic - Claude AI assistant