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