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

1. 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

2. 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])