MCP Ethers Wallet
A Model Context Protocol (MCP) server that provides Ethereum wallet functionality using ethers.js v6.
Overview
The MCP Ethers Wallet exposes Ethereum functionality to LLM applications through the Model Context Protocol. It provides tools for:
- Network information and management
- Wallet creation and management
- Transaction creation and sending
- Contract interaction (ERC20, ERC721, ERC1155)
- ENS resolution
- Unit conversion
- Gas estimation
- Transaction history
This server follows the MCP specification, making it compatible with any MCP client, such as Claude Desktop.
Using with MCP Tools
To use this as an MCP server with tools like Claude Desktop, use the following configuration:
Replace `pathTo/ethers-server` with the actual path to your installation directory, and add your API keys.
Installation
Quick Start
Starting the Server
Using with Claude Desktop
- Configure Claude Desktop to use this server: - Go to Settings > Model Context Protocol - Set Command to: `node path/to/ethers-server/build/src/mcpServer.js`
- Use the Ethers tools in your Claude conversations.
Testing with MCP Inspector
The MCP Inspector is a tool for testing and debugging MCP servers.
Configuration
Environment Variables
Create a `.env` file in the root directory with:
Network Configuration
The server supports multiple Ethereum and EVM-compatible networks. The supported networks are defined in `src/config/networkList.ts`:
Mainnet Networks
- Ethereum (ETH)
- Polygon PoS (POL)
- Arbitrum (ETH)
- Arbitrum Nova (ETH)
- Optimism (ETH)
- Avalanche C-Chain (AVAX)
- Base (ETH)
- Polygon zkEVM (ETH)
- Linea (ETH)
- BNB Smart Chain (BNB)
- Scroll (ETH)
- Rari Chain Mainnet (ETH)
- Berachain (BERA)
- Sonic Mainnet (S)
Testnet Networks
- Monad Testnet (MON)
- MEGA Testnet (ETH)
You can specify a network when using tools with the `provider` parameter, e.g., `"provider": "polygon"` or `"provider": "bera"`.
Custom RPC URLs
You can also use a custom RPC URL:
Available Tools
Core Network Tools
- **getSupportedNetworks**: Get a list of all supported networks and their configurations
- **getBlockNumber**: Get the current block number
- **getBlockDetails**: Get details about a block
- **getTransactionDetails**: Get details about a transaction
- **getGasPrice**: Get the current gas price
- **getFeeData**: Get the current network fee data
Wallet Tools
- **generateWallet**: Generate a new Ethereum wallet
- **loadWallet**: Load an existing wallet from a private key
- **checkWalletExists**: Check if a wallet is configured on the server
- **getWalletBalance**: Get the ETH balance of a wallet
- **getWalletTransactionCount**: Get the number of transactions sent by an address
- **signMessage**: Sign a message with the loaded wallet
- **ethSign**: Sign data using the Ethereum eth_sign method (legacy)
Contract Tools
- **getContractCode**: Get a contract's bytecode
- **callContractMethod**: Call a read-only method on a contract
- **estimateGas**: Estimate gas for a transaction
ENS Tools
- **lookupAddress**: Get the ENS name for an address
- **resolveName**: Get the address for an ENS name
Unit Conversion Tools
- **formatEther**: Convert a wei value to a decimal string in ether
- **parseEther**: Convert an ether value to wei
- **formatUnits**: Convert a value to a decimal string with specified units
ERC20 Tools
- **erc20GetTokenInfo**: Get basic token information (name, symbol, decimals)
- **erc20GetBalance**: Get token balance for an address
- **erc20Transfer**: Transfer tokens between accounts
- **erc20GetAllowance**: Get token approval allowance
- **erc20Approve**: Approve tokens for spending by another address
ERC721 Tools
- **erc721GetTokenInfo**: Get basic NFT collection information
- **erc721GetBalance**: Get NFT balance for an address
- **erc721OwnerOf**: Get the owner of a specific NFT
- **erc721GetTokenURI**: Get token URI metadata for an NFT
- **erc721Transfer**: Transfer an NFT to another address
- **erc721SafeTransfer**: Safely transfer an NFT to another address
ERC1155 Tools
- **erc1155GetTokenInfo**: Get basic multi-token information
- **erc1155GetBalance**: Get token balance for an address and token ID
- **erc1155GetBatchBalance**: Get multiple token balances in a single call
- **erc1155GetURI**: Get metadata URI for a token
- **erc1155SafeTransfer**: Safely transfer tokens to another address
- **erc1155SafeBatchTransfer**: Safely transfer multiple tokens in a single call
Tool Usage Examples
Getting Network Information
Getting Wallet Balance
Getting ERC20 Token Information
Calling a Contract Method
Caching
The server implements caching for certain operations to improve performance and reduce API calls:
- Token information (name, symbol, decimals)
- Token balances
- Contract method calls
The cache uses a time-to-live (TTL) mechanism that automatically expires entries after a configurable period.
Rate Limiting
The server implements rate limiting for certain operations:
- Write operations (transfers, approvals)
- Wallet generation
- Contract interactions
This prevents abuse and ensures the server remains responsive.
Error Handling
The server includes comprehensive error handling:
- Custom error classes for specific error types
- Detailed error messages
- Appropriate HTTP status codes
- Safe error serialization to prevent sensitive data leaks
Development
Building
Testing
The server includes comprehensive test suites:
Running All Tests with Bun (Recommended)
Running MCP Client Tests
These tests validate the MCP protocol implementation by spawning the server and sending real MCP requests:
Individual Test Categories
Test Environment
Tests use the `bun.setup.ts` file to configure the test environment, including setting up Hardhat as the default provider.
Security Considerations
- **Private Keys**: The server can store private keys in memory. Exercise caution with the `saveToEnv` option in wallet operations.
- **API Keys**: Your Alchemy and Infura API keys are used to connect to Ethereum networks. Never expose your `.env` file.
- **Eth Sign**: The `ethSign` method can sign transaction-like data, which is less secure than `signMessage`. Use with caution.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT
Author
Dennison Bertram (dennison@tally.xyz)