Hyperlane MCP Server
A powerful Model Context Protocol (MCP) server that provides seamless integration with the Hyperlane protocol, enabling LLM assistants to interact with cross-chain messaging and smart contracts across multiple blockchains.
Table of Contents
- Overview
- How It Works
- Features
- Requirements
- Installation & Setup
- Configuration
- Usage
- Available Tools
- Project Structure
- Files & Folders Created
- Examples
- Troubleshooting
- Contributing
- License
Overview
The Hyperlane MCP Server bridges the gap between LLM assistants and the Hyperlane cross-chain infrastructure. It provides a standardized interface for deploying chains, managing validators and relayers, sending cross-chain messages, and deploying warp routes for asset transfers.
How It Works
Architecture
The server operates as an MCP (Model Context Protocol) server that:
- Connects to Multiple Blockchains: Uses Hyperlane's MultiProvider to manage connections to various blockchain networks
- Manages Local Registry: Maintains a local cache of chain metadata, deployed contracts, and warp route configurations
- Deploys Infrastructure: Handles deployment of Hyperlane core contracts, validators, and relayers
- Facilitates Cross-Chain Operations: Enables message passing and asset transfers between chains
- Provides Docker Integration: Runs validators and relayers in Docker containers for isolation
Core Components
- LocalRegistry: Extends Hyperlane's registry system with local storage capabilities
- HyperlaneDeployer: Handles deployment of core Hyperlane contracts
- ValidatorRunner: Manages validator Docker containers
- RelayerRunner: Manages relayer Docker containers
- WarpRoute: Handles deployment and management of cross-chain asset routes
Features
Cross-Chain Messaging
- Send messages between different blockchain networks
- Monitor message delivery status
- Handle message verification and execution
Contract Deployment & Management
- Deploy Hyperlane core contracts to new chains
- Deploy and configure warp routes for asset transfers
- Manage contract configurations and upgrades
Infrastructure Management
- Run validators for message verification
- Run relayers for message delivery
- Monitor validator and relayer health
- Handle Docker container lifecycle
Asset Transfers
- Deploy warp routes for cross-chain asset transfers
- Execute multi-hop asset transfers
- Support various token types (native, synthetic, collateral, etc.)
Requirements
System Requirements
- Node.js: v18 or higher
- Package Manager: pnpm (recommended)
- Docker: For running validators and relayers
- Operating System: Linux, macOS, or Windows with WSL2
Network Requirements
- Access to RPC endpoints for target blockchain networks
- Stable internet connection for cross-chain operations
- Sufficient bandwidth for Docker image downloads
Blockchain Requirements
- Private key with sufficient native tokens for gas fees
- Access to blockchain RPC endpoints
- Understanding of target chain configurations
Installation & Setup
1. Clone the Repository
git clone https://github.com/yourusername/hyperlane-mcp.git
cd hyperlane-mcp
2. Install Dependencies
# Install pnpm if not already installed
npm install -g pnpm
# Install project dependencies
pnpm install
3. Build the Project
pnpm build
4. Set Up Environment Variables
Create a .env file in the project root:
cp .env.example .env
Edit the .env file with your configuration:
# Required: Private key for signing transactions (without 0x prefix)
PRIVATE_KEY=your_private_key_here
# Required: GitHub Personal Access Token for registry access
GITHUB_TOKEN=your_github_personal_access_token
# Optional: Custom cache directory (defaults to ~/.hyperlane-mcp)
CACHE_DIR=/path/to/custom/cache/directory
5. Verify Docker Installation
# Ensure Docker is running
docker --version
docker ps
Configuration
Environment Variables
| Variable | Required | Description | Default |
|---|---|---|---|
PRIVATE_KEY | Yes | Private key for transaction signing (without 0x prefix) | None |
GITHUB_TOKEN | Yes | GitHub PAT for accessing Hyperlane registry | None |
CACHE_DIR | No | Directory for storing local data | ~/.hyperlane-mcp |
HOME | No | Home directory (fallback for CACHE_DIR) | System default |
MCP Client Configuration
For Claude Desktop or other MCP clients, add this configuration:
{
"mcpServers": {
"hyperlane": {
"command": "node",
"args": [
"/path/to/hyperlane-mcp/build/index.js"
],
"env": {
"PRIVATE_KEY": "your_private_key",
"GITHUB_TOKEN": "your_github_token"
"CACHE_DIR": "your_cache_dir"
}
}
}
}
Usage
Starting the Server
# Development mode
pnpm start
# Production mode
node build/index.js
# With MCP Inspector (for debugging)
pnpm inspect
Basic Workflow
- Deploy a New Chain: Use
deploy-chaintool to add a new blockchain - Run Validator: Use
run-validatorto start message validation - Run Relayer: Use
run-relayerto enable message delivery - Deploy Warp Route: Use
deploy-warp-routefor asset transfers - Send Messages/Assets: Use transfer tools for cross-chain operations
Available Tools
Chain Management
deploy-chain: Deploy Hyperlane core contracts to a new chainrun-validator: Start a validator for a specific chainrun-relayer: Start a relayer for cross-chain message delivery
Cross-Chain Operations
cross-chain-message-transfer: Send messages between chainscross-chain-asset-transfer: Transfer assets using warp routes
Warp Route Management
deploy-warp-route: Deploy new warp routes for asset transfers
Resources
- Warp Route Configs: Access via
hyperlane-warp:///{symbol}/{/chain*}URI
Project Structure
hyperlane-mcp/
├── src/ # Source code
│ ├── index.ts # Main MCP server entry point
│ ├── localRegistry.ts # Local registry implementation
│ ├── hyperlaneDeployer.ts # Core contract deployment
│ ├── RunValidator.ts # Validator Docker management
│ ├── RunRelayer.ts # Relayer Docker management
│ ├── warpRoute.ts # Warp route deployment
│ ├── msgTransfer.ts # Message transfer logic
│ ├── assetTransfer.ts # Asset transfer logic
│ ├── config.ts # Configuration utilities
│ ├── utils.ts # Utility functions
│ ├── types.ts # Type definitions
│ ├── logger.ts # Logging configuration
│ ├── gcr.ts # Google Container Registry utilities
│ ├── file.ts # File system utilities
│ ├── configOpts.ts # Configuration options
│ └── consts.ts # Constants
├── build/ # Compiled JavaScript output
├── node_modules/ # Dependencies
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── .env # Environment variables (create this)
└── README.md # This file
Files & Folders Created
The server creates and manages several directories and files during operation:
Cache Directory Structure
~/.hyperlane-mcp/ # Main cache directory
├── chains/ # Chain configurations
│ ├── {chainName}.yaml # Chain metadata
│ ├── {chainName}.deploy.yaml # Deployed contract addresses
│ └── {chainName}-core-config.yaml # Core deployment config
├── routes/ # Warp route configurations
│ └── {symbol}-{hash}.yaml # Warp route configs
├── agents/ # Agent configurations
│ └── {chainName}-agent-config.json # Validator/relayer configs
└── logs/ # Runtime data and logs
├── hyperlane_db_validator_{chain}/ # Validator database
├── hyperlane_db_relayer/ # Relayer database
└── hyperlane-validator-signatures-{chain}/ # Validator signatures
File Types Created
Chain Configuration Files
{chainName}.yaml: Contains chain metadata (RPC URLs, chain ID, native token info){chainName}.deploy.yaml: Deployed contract addresses (mailbox, ISM, hooks, etc.){chainName}-core-config.yaml: Core deployment configuration
Warp Route Files
{symbol}-{hash}.yaml: Warp route configuration for cross-chain asset transfers
Agent Configuration Files
{chainName}-agent-config.json: Configuration for validators and relayers
Docker Volumes
- Validator databases: Persistent storage for validator state
- Relayer databases: Persistent storage for relayer state
- Signature storage: Validator checkpoint signatures
Temporary Files
- Docker containers: Validator and relayer containers (managed automatically)
- Log files: Runtime logs from validators and relayers
Examples
1. Deploy a New Chain
Deploy Hyperlane core contracts to a new blockchain called "mytestnet" with chain ID 12345, RPC URL "https://rpc.mytestnet.com", native token symbol "MTN", and token name "MyTestNet Token". This should be marked as a testnet.
2. Send Cross-Chain Message
Send a cross-chain message from Ethereum to Polygon. The recipient address should be 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6 and the message body should be "Hello from Ethereum!"
3. Deploy Warp Route
Deploy a warp route for asset transfers between Ethereum and Arbitrum chains. Use collateral token type for Ethereum and synthetic token type for Arbitrum.
4. Transfer Assets
Transfer assets using the USDC warp route from Ethereum to Arbitrum. Transfer 100 USDC to recipient address 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6. First, fetch the warp route configuration for USDC on these chains using the resources.
5. Run Infrastructure
Start a validator for the "mytestnet" chain that we deployed earlier.
Start a relayer to handle message delivery between Ethereum and mytestnet chains. Use "mytestnet" as the validator chain name.
6. Multi-Chain Asset Transfer
Transfer 50 USDC from Ethereum to Polygon, then from Polygon to Arbitrum, using the existing USDC warp routes. The final recipient should be 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6.
7. Check Warp Route Resources
Show me the available warp route configurations for USDC token across Ethereum and Polygon chains.
8. Deploy Custom Token Route
Deploy a new warp route for a custom token called "MyToken" (symbol: MTK) between three chains: Ethereum (collateral type), Polygon (synthetic type), and Arbitrum (synthetic type).
Troubleshooting
Common Issues
1. Docker Permission Errors
# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Restart shell or logout/login
2. Insufficient Gas Fees
- Ensure your wallet has sufficient native tokens for gas
- Check current gas prices on target networks
3. RPC Connection Issues
- Verify RPC URLs are accessible
- Check for rate limiting on RPC providers
- Consider using multiple RPC endpoints
4. Container Startup Failures
# Check Docker logs
docker logs <container_id>
# Verify Docker image availability
docker pull gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0
Debug Mode
Run with MCP Inspector for detailed debugging:
pnpm inspect
Log Files
Check logs in the cache directory:
# Validator logs
tail -f ~/.hyperlane-mcp/logs/validator-{chain}.log
# Relayer logs
tail -f ~/.hyperlane-mcp/logs/relayer.log
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Development Setup
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Code Style
- Use TypeScript for all new code
- Follow existing code formatting (Prettier)
- Add JSDoc comments for public APIs
- Include error handling
Authors
License
This project is licensed under the MIT License.
Disclaimer
The software is provided as is. No guarantee, representation or warranty is being made, express or implied, as to the safety or correctness of the software. It has not been audited and as such there can be no assurance it will work as intended. Users may experience delays, failures, errors, omissions, loss of transmitted information or loss of funds. The creators are not liable for any of the foregoing. Users should proceed with caution and use at their own risk.