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:
{
"ethers": {
"command": "node",
"args": [
"pathTo/ethers-server/build/src/mcpServer.js"
],
"env": {
"ALCHEMY_API_KEY": "key goes here",
"INFURA_API_KEY": "key goes here"
}
}
}
Replace pathTo/ethers-server with the actual path to your installation directory, and add your API keys.
Installation
# Clone the repository
git clone https://github.com/yourusername/ethers-server.git
cd ethers-server
# Install dependencies
npm install
# Build the TypeScript code
npm run build
Quick Start
Starting the Server
# Using Node.js
npm start
# Using Bun (recommended for faster performance)
bun start
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.
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector
# Run it with your server
mcp-inspector --command "node build/src/mcpServer.js"
Configuration
Environment Variables
Create a .env file in the root directory with:
# Required
ALCHEMY_API_KEY=your_alchemy_api_key
INFURA_API_KEY=your_infura_api_key
# Optional
DEFAULT_NETWORK=mainnet # Default: mainnet
LOG_LEVEL=info # Default: info (options: error, warn, info, debug)
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:
"provider": "https://my-custom-rpc.example.com"
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
{
"name": "getSupportedNetworks",
"arguments": {}
}
Getting Wallet Balance
{
"name": "getWalletBalance",
"arguments": {
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"provider": "mainnet"
}
}
Getting ERC20 Token Information
{
"name": "erc20GetTokenInfo",
"arguments": {
"tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"provider": "mainnet"
}
}
Calling a Contract Method
{
"name": "callContractMethod",
"arguments": {
"contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"methodName": "symbol",
"params": [],
"abi": ["function symbol() view returns (string)"],
"provider": "mainnet"
}
}
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
npm run build
Testing
The server includes comprehensive test suites:
Running All Tests with Bun (Recommended)
# Start a Hardhat node in a separate terminal
npx hardhat node
# Run all tests
bun test
Running MCP Client Tests
These tests validate the MCP protocol implementation by spawning the server and sending real MCP requests:
bun run test:client:mcp
Individual Test Categories
# Run ERC20 tests
bun test src/services/erc/erc20.test.ts
# Run ERC721 tests
bun test src/services/erc/erc721.test.ts
# Run ERC1155 tests
bun test src/services/erc/erc1155.test.ts
# Run core tool tests
bun test src/tests/write-methods.test.ts
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 ([email protected])
