中文文档

@sinco-lab/evm-mcp-server

An EVM interaction service gateway based on Model Context Protocol (MCP) and Viem, enabling AI agents or services to securely interact with a configured EVM-compatible blockchain.

📋 Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Connecting from Clients (Cursor, Claude)
• Available Tools
• Security Considerations
• Project Structure
• Development Scripts
• License

🔭 Overview

This project provides a Model Context Protocol (MCP) server designed to act as a gateway for interacting with an EVM-compatible blockchain. It leverages the powerful Viem library for blockchain interactions and the MCP SDK to expose these capabilities as tools consumable by AI agents or other MCP clients.

The server connects to a specific EVM chain configured via environment variables and allows clients to perform various read and write operations through a standardized MCP interface.

✨ Features

• MCP Integration: Exposes EVM functionalities as standard MCP tools.
• Viem Powered: Utilizes the modern and efficient Viem library for reliable EVM interactions.
• Configurable Endpoint: Connects to any EVM-compatible chain via an RPC URL defined in the environment setup.
• Core EVM Operations: Provides tools for common tasks like checking balances, transferring native tokens and ERC20 tokens, signing messages, and interacting with contracts (reading allowance, approving, etc.).
• Type Safe: Developed entirely in TypeScript for better maintainability and developer experience.

🛠️ Prerequisites

• Node.js version 18.0.0 or higher.
• pnpm package manager.

📦 Installation

1. Clone the repository:

   git clone https://github.com/sinco-lab/evm-mcp-server.git
   cd evm-mcp-server
   

2. Install dependencies using pnpm:

   pnpm install
   

⚙️ Configuration

Configuration is primarily handled via environment variables. The server requires:

• WALLET_PRIVATE_KEY: The private key (starting with 0x) of the wallet the server will use. Keep this secure!
• RPC_PROVIDER_URL: The JSON-RPC endpoint URL for the target EVM network.

These can be provided either through a .env file (for testing client and debugging) or directly within the client's MCP server configuration (see below).

🚀 Usage

Build the Project

Compile the TypeScript source code into JavaScript:

pnpm run build

This command generates the build directory containing build/evm.js.

Start the MCP Server Manually (Stdio Mode)

If using a .env file for configuration:

1. Copy .env.example to .env.
2. Fill in WALLET_PRIVATE_KEY and RPC_PROVIDER_URL in .env.
3. Run the server:

   # Loads .env automatically if available in current or parent dirs
   node build/evm.js
   

   (Note: node itself doesn't source .env, but the dotenv package used in src/evm.ts does)

Run the Example Test Client

This project includes a simple test client (test/client.ts) that uses StdioClientTransport to automatically start the server process (node build/evm.js) based on its configuration.

Prerequisites:

1. Build the project: pnpm run build
2. Create and configure your .env file (the client script sources this).

Run the client:

pnpm run test

This command uses tsx (via package.json) to execute test/client.ts. The client script will read .env, start the server process, connect to it via stdio, list available tools, and call the getChain tool.

Debugging with MCP Inspector

Requires a configured .env file and built project.

pnpm run debug

This script sources the .env file and launches the inspector connected to the server script (build/evm.js), passing necessary environment variables.

🔌 Connecting from Clients (Cursor, Claude)

You can configure clients like Cursor or the Claude Desktop app to automatically start and connect to this MCP server.

Prerequisites:

1. Install dependencies: pnpm install
2. Build the project: pnpm run build

Security Warning: The following configurations involve placing your WALLET_PRIVATE_KEY and RPC_PROVIDER_URL directly into configuration files (.cursor/mcp.json or claude_desktop_config.json). These files might be stored in less secure ways than a .env file and could potentially be synced or backed up unintentionally. Understand the risks before placing sensitive information directly in these configuration files. For higher security needs, explore alternative key management strategies not covered here.

Common mcpServers Configuration Structure

The following is the basic JSON structure needed to configure the MCP server, usable for both Cursor and Claude Desktop:

// Common mcpServers structure
{
  "mcpServers": {
    // Option 1: Run locally built server
    "local-evm-mcp-dev": {
      "command": "node", // Use node directly
      "args": [
        "/path/to/your/project/build/evm.js" // Use absolute path
      ],
      "env": {
        // WARNING: Security risk! Use a new key (see Security Considerations).
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      },
    },
    // Option 2: Run published package via npx (if applicable)
    "npx-evm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@sinco-lab/evm-mcp-server" // Use your published package name
      ],
      "env": {
        // WARNING: Security risk! Use a new key (see Security Considerations).
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      }
    }
  }
}

IMPORTANT: Standard JSON files do not allow comments. Please remove all lines starting with // before using this configuration.

Connecting from Cursor (Recommended Method)

The recommended way to configure Cursor is using a .cursor/mcp.json file within your project.

1. Create a directory named .cursor in your project root if it doesn't exist.
2. Create a file named mcp.json inside the .cursor directory.
3. Copy the Common mcpServers Configuration Structure above into the mcp.json file. Replace the placeholder values with your actual private key and RPC URL, and ensure all comments are removed.
4. Restart Cursor or reload the project. Enable the desired server (local-evm-mcp-dev or npx-evm-mcp) in Cursor's MCP settings.

(Manual setup via Cursor Settings UI is possible but less recommended for project-specific configurations.)

Connecting from Claude Desktop App

If the Claude Desktop app supports a configuration file (check its documentation for the exact path and format, often similar to the example below):

1. Locate or create the Claude Desktop configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\\Claude\\claude_desktop_config.json on Windows).

2. Merge the "mcpServers" key and its content from the Common mcpServers Configuration Structure above into the Claude main configuration file. Replace placeholders with your actual private key and RPC URL, ensuring comments are removed. If the file already exists, merge the JSON objects carefully to avoid breaking existing Claude settings.

   Note: As mentioned in the common structure's comments, ensure the command, args settings are correct for the environment where the Claude Desktop app runs.

3. Restart the Claude Desktop app.

Recommendation: Prefer using the configuration file methods (Cursor's mcp.json or Claude Desktop's config file) with the env field, while being aware of the inherent risks of storing secrets in configuration files.

🛠️ Available Tools

The server currently exposes the following tools via the Model Context Protocol:

| Tool Name | Description | | :-------------------- | :------------------------------------------------------------------------------ | | getAddress | Get the connected wallet address configured on the server. | | getChain | Get the chain ID and name the server is connected to. | | getBalance | Get the native token balance for a given address (or the server's wallet). | | signMessage | Sign a message using the server's configured wallet. | | sendNativeToken | Send native tokens (e.g., ETH) from the server's wallet to a recipient. | | getTokenBalance | Get the ERC20 token balance for a specified owner address. | | transferToken | Send a specified amount of an ERC20 token from the server's wallet. | | getTokenTotalSupply | Get the total supply of an ERC20 token. | | getTokenAllowance | Get the allowance an owner has granted to a spender for an ERC20 token. | | approveToken | Approve a spender to withdraw an ERC20 token from the server's wallet. | | revokeApproval | Revoke (set to 0) a spender's allowance for an ERC20 token. | | transferTokenFrom | Transfer ERC20 tokens from one address to another (requires prior approval). | | convertToBaseUnit | Convert a decimal token amount to its base unit representation (e.g., wei). | | convertFromBaseUnit | Convert a token amount from its base unit representation to a decimal string. |

(Refer to src/evm-tools.ts for detailed parameter and return value schemas)

🔒 Security Considerations

• Private Key Management: Directly embedding WALLET_PRIVATE_KEY in configuration files (.cursor/mcp.json, claude_desktop_config.json) or using a .env file carries security risks. Never commit files containing private keys to version control. For production or high-value scenarios, use dedicated secret management solutions. To mitigate risks, it is strongly recommended to create a new, dedicated wallet private key for development and testing purposes. Do not use your main wallet key holding significant funds here.
• RPC Endpoint Security: Ensure your RPC_PROVIDER_URL points to a trusted node.
• Access Control: The server running in stdio mode lacks built-in access control. Secure the environment where the server process runs.

📁 Project Structure

evm-mcp-server/
├── src/                # Core source code for the server and tools
│   ├── evm.ts          # Main server entry point logic
│   └── evm-tools.ts    # Definitions and logic for all MCP tools
├── test/               # Test client code
│   └── client.ts       # Example MCP client for testing the server
├── build/              # Compiled JavaScript output (generated by `pnpm run build`)
├── .env.example        # Example environment file template
├── .env                # Environment variables (Gitignored, needs creation)
├── .gitignore
├── package.json        # Project manifest and dependencies
├── pnpm-lock.yaml      # Lockfile for pnpm
├── tsconfig.json       # TypeScript compiler configuration
└── README.md           # This file
└── README.zh.md        # Chinese version of README

💻 Development Scripts

Key scripts defined in package.json:

• pnpm run build: Compiles TypeScript code in src/ to JavaScript in build/.
• pnpm run test: Runs the example test client (test/client.ts) using tsx. The client starts the server process itself (requires .env).
• pnpm run clean: Removes the build/ directory.
• pnpm run debug: Starts the server with the MCP Inspector attached for debugging (requires .env).
• pnpm run prepublishOnly: Automatically cleans and builds the project before publishing to npm.

📄 License

This project is licensed under the terms of the MIT License.