EVM MCP Server

To modify or extend the server's functionality, follow these steps based on the project structure:

1. Add new services: Create new files under src/core/services/.
2. Register new tools: Add your tool definitions in src/core/tools.ts.
3. Register new resources: Add your resource URI patterns in src/core/resources.ts.
4. Add network support: Update src/core/chains.ts to include new EVM networks.
5. Configure the server: Edit hardcoded values in src/server/http-server.ts to change server configuration.

To install the server, clone the repository and use either bun (recommended) or npm to install dependencies.

Prerequisites:

• Bun 1.0.0 or higher (recommended)
• Node.js 20.0.0 or higher (if not using Bun)
• Optional: Etherscan API key for automatic ABI fetching.

# Clone the repository
git clone https://github.com/mcpdotdirect/evm-mcp-server.git
cd evm-mcp-server

# Install dependencies with Bun
bun install

# Or with npm
npm install

To use the EVM MCP server within the Cursor editor, you can add it via the UI or use a portable .cursor/mcp.json configuration file.

Via Cursor Settings

1. Open Settings (gear icon).
2. Click Features.
3. Scroll to MCP Servers and click Add new MCP server.
4. Use these details:
   • Server name: evm-mcp-server
   • Type: command
   • Command: npx @mcpdotdirect/evm-mcp-server

Via .cursor/mcp.json (Recommended for teams)

Create a .cursor/mcp.json file in your project root to version control your configuration. This allows you to define both stdio and HTTP modes.

{
  "mcpServers": {
    "evm-mcp-server": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server"]
    },
    "evm-mcp-http": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"]
    }
  }
}

You can add and start the EVM MCP server using the Claude CLI with the following commands:

# Add the MCP server
claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server

# Start Claude with the MCP server enabled
claude

If you have the repository cloned locally, you can use bun to manage different server modes and development environments.

stdio mode (for CLI tools)

• bun start: Starts the standard stdio server.
• bun dev: Starts the server in development mode with auto-reload.

HTTP mode with SSE (for web applications)

• bun start:http: Starts the HTTP server.
• bun dev:http: Starts the HTTP server in development mode with auto-reload.

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

You can run the server immediately without a local installation using npx. Use the default mode for CLI tools (stdio) or append the --http flag for web applications (HTTP mode).

# Run the server in stdio mode (for CLI tools)
npx @mcpdotdirect/evm-mcp-server

# Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/evm-mcp-server --http

When using the EVM MCP Server, especially in production, adhere to the following security guidelines:

• Private Key Safety: The server uses private keys only for transaction signing; it does not store them.
• Transport Security: Use HTTPS for the HTTP server in production environments.
• Access Control: Implement additional authentication mechanisms for production use.
• Abuse Prevention: Implement rate limiting to prevent service abuse.
• High-Value Transactions: For sensitive operations, implement manual confirmation steps.

The evm-mcp-server core services are organized into specialized modules. You can import specific service logic from the following exported modules:

• clients: Low-level blockchain clients.
• balance: Balance-related queries.
• transfer: Token and native asset transfer operations.
• blocks: Block data retrieval.
• transactions: Transaction history and status.
• contracts: Smart contract interaction services.
• tokens: ERC-20 and other token services.
• ens: ENS (Ethereum Name Service) resolution.
• abi: ABI (Application Binary Interface) management.
• wallet: Wallet and key management.
• helpers: Utility functions (exported as helpers).

To perform write operations (transfers, contract writes, signing), you must configure a wallet using either a private key or a mnemonic phrase via environment variables.

Option 1: Private Key Use EVM_PRIVATE_KEY with the hex format (with or without 0x prefix).

Option 2: Mnemonic Phrase (Recommended for HD Wallets) Use EVM_MNEMONIC with a BIP-39 standard phrase. You can also specify an account index for HD derivation.

Supported Write Tools:

• transfer_native
• transfer_erc20
• approve_token_spending
• write_contract
• sign_message
• sign_typed_data

# Private Key
export EVM_PRIVATE_KEY="0x..."

# Mnemonic Phrase
export EVM_MNEMONIC="word1 word2 word3 ... word12"
export EVM_ACCOUNT_INDEX="0" # Optional: default is 0

For web applications that need to connect to the MCP server from a browser or environments where local commands are not ideal, use the Server-Sent Events (SSE) configuration in your .cursor/mcp.json file.

{
  "mcpServers": {
    "evm-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

To enable automatic ABI fetching for smart contract interactions (e.g., using the get_contract_abi tool or read_contract with abiJson), configure the ETHERSCAN_API_KEY environment variable. This single key works across all 60+ supported EVM networks via the Etherscan v2 API.

export ETHERSCAN_API_KEY="your-api-key-here"