@sinco-lab/evm-mcp-server

中文文档

@sinco-lab/evm-mcp-server

Model Context Protocol（MCP）と Viem に基づく EVM インタラクションサービスのゲートウェイです。AI エージェントやサービスが、設定済みの EVM 互換ブロックチェーンと安全にやり取りできるようにします。

📋 目次

• 概要
• 機能
• 前提条件
• インストール
• 設定
• 使い方
• クライアント（Cursor、Claude）からの接続
• 利用可能なツール
• セキュリティに関する考慮事項
• プロジェクト構成
• 開発用スクリプト
• ライセンス

🔭 概要

このプロジェクトは、EVM 互換ブロックチェーンとやり取りするためのゲートウェイとして機能する、Model Context Protocol（MCP）サーバーを提供します。ブロックチェーンとのやり取りには強力な Viem ライブラリを活用し、MCP SDK を使用して、AI エージェントやその他の MCP クライアントが利用できるツールとして機能を公開します。

サーバーは、環境変数で設定された特定の EVM チェーンに接続し、標準化された MCP インターフェースを通じて、クライアントがさまざまな読み取りおよび書き込み操作を実行できるようにします。

✨ 機能

• MCP 連携：EVM の機能を標準的な MCP ツールとして公開します。
• Viem を活用：最新かつ効率的な Viem ライブラリを使用し、信頼性の高い EVM 操作を実現します。
• エンドポイント設定：環境設定で指定した RPC URL を使用して、任意の EVM 互換チェーンに接続します。
• EVM の主要な操作：残高の確認、ネイティブトークンおよび ERC20 トークンの転送、メッセージへの署名、コントラクトとのやり取り（allowance の読み取り、承認など）といった一般的なタスク用のツールを提供します。
• 型安全：保守性と開発者エクスペリエンスを向上させるため、すべて TypeScript で開発されています。

🛠️ 前提条件

• Node.js バージョン 18.0.0 以上。
• pnpm パッケージマネージャー。

📦 インストール

1. リポジトリをクローンします：

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

2. pnpm を使用して依存関係をインストールします：

   pnpm install
   

⚙️ 設定

設定は主に環境変数で行います。サーバーには次の環境変数が必要です。

• WALLET_PRIVATE_KEY：サーバーが使用するウォレットの秘密鍵（0x で始まるもの）です。安全に保管してください！
• RPC_PROVIDER_URL：対象の EVM ネットワークの JSON-RPC エンドポイント URL です。

これらは、.env ファイル（クライアントのテストやデバッグ用）またはクライアントの MCP サーバー設定に直接指定できます（以下を参照）。

🚀 使い方

プロジェクトをビルドする

TypeScript のソースコードを JavaScript にコンパイルします。

pnpm run build

このコマンドにより、build/evm.js を含む build ディレクトリが生成されます。

MCP サーバーを手動で起動する（Stdio モード）

設定に .env ファイルを使用する場合：

1. .env.example を .env にコピーします。
2. .env 内の WALLET_PRIVATE_KEY と RPC_PROVIDER_URL に値を設定します。
3. サーバーを実行します：

   # 現在のディレクトリまたは親ディレクトリに .env がある場合、自動的に読み込みます
   node build/evm.js
   

   （注：node 自体は .env を読み込みませんが、src/evm.ts で使用されている dotenv パッケージが読み込みます）

サンプルのテストクライアントを実行する

このプロジェクトには、StdioClientTransport を使用して、設定に基づいてサーバープロセス（node build/evm.js）を自動的に起動する、シンプルなテストクライアント（test/client.ts）が含まれています。

前提条件：

1. プロジェクトをビルドします：pnpm run build
2. .env ファイルを作成して設定します（クライアントスクリプトがこのファイルを読み込みます）。

クライアントを実行します：

pnpm run test

このコマンドは、tsx（package.json 経由）を使用して test/client.ts を実行します。クライアントスクリプトは .env を読み込み、サーバープロセスを起動し、stdio 経由で接続して、利用可能なツールを一覧表示し、getChain ツールを呼び出します。

MCP Inspector でデバッグする

設定済みの .env ファイルとビルド済みのプロジェクトが必要です。

pnpm run debug

このスクリプトは .env ファイルを読み込み、必要な環境変数を渡して、サーバースクリプト（build/evm.js）に接続した Inspector を起動します。

🔌 クライアント（Cursor、Claude）から接続する

Cursor や Claude Desktop アプリなどのクライアントを設定すると、この MCP サーバーを自動的に起動して接続できます。

前提条件：

1. 依存関係をインストールします：pnpm install
2. プロジェクトをビルドします：pnpm run build

セキュリティに関する警告： 以下の設定では、WALLET_PRIVATE_KEY と RPC_PROVIDER_URL を設定ファイル（.cursor/mcp.json または claude_desktop_config.json）に直接記述します。これらのファイルは .env ファイルより安全性の低い方法で保存される可能性があり、意図せず同期またはバックアップされるおそれがあります。機密情報をこれらの設定ファイルに直接記述する前に、リスクを理解してください。 より高いセキュリティが必要な場合は、ここでは説明していない別のキー管理方法を検討してください。

共通の mcpServers 設定構造

以下は、Cursor と Claude Desktop の両方で使用できる、MCP サーバーの設定に必要な基本的な JSON 構造です。

// 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"
      }
    }
  }
}

重要： 標準の JSON ファイルではコメントを使用できません。この設定を使用する前に、// で始まる行をすべて削除してください。

Cursor から接続する（推奨方法）

Cursor の設定には、プロジェクト内の .cursor/mcp.json ファイルを使用する方法を推奨します。

1. プロジェクトのルートに .cursor ディレクトリがない場合は作成します。
2. .cursor ディレクトリ内に mcp.json ファイルを作成します。
3. 上記の共通の mcpServers 設定構造を mcp.json ファイルにコピーします。プレースホルダーの値を実際の秘密鍵と RPC URL に置き換え、コメントをすべて削除してください。
4. Cursor を再起動するか、プロジェクトを再読み込みします。Cursor の MCP 設定で、目的のサーバー（local-evm-mcp-dev または npx-evm-mcp）を有効にします。

(Cursor の設定 UI から手動で設定することもできますが、プロジェクト固有の設定にはあまり推奨されません。)

Claude Desktop アプリから接続する

Claude Desktop アプリが設定ファイルに対応している場合は（正確なパスと形式についてはドキュメントを確認してください。多くの場合、以下の例と同様です）：

1. Claude Desktop の設定ファイルを探すか、作成します（例：macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\\Claude\\claude_desktop_config.json）。

2. 上記の共通の mcpServers 設定構造から "mcpServers" キーとその内容を、Claude のメイン設定ファイルに統合します。プレースホルダーを実際の秘密鍵と RPC URL に置き換え、コメントを削除してください。ファイルがすでに存在する場合は、既存の Claude 設定を壊さないよう、JSON オブジェクトを慎重に統合してください。

   注：共通構造内のコメントにも記載されているように、Claude Desktop アプリが実行される環境に合わせて、command と args の設定が正しいことを確認してください。

3. Claude Desktop アプリを再起動します。

推奨： env フィールドを使用する設定ファイル方式（Cursor の mcp.json または Claude Desktop の設定ファイル）を優先してください。ただし、設定ファイルにシークレットを保存することに伴うリスクには注意してください。

🛠️ 利用可能なツール

サーバーは現在、Model Context Protocol を通じて以下のツールを公開しています。

ツール名	説明
getAddress	サーバーに設定されている接続済みウォレットのアドレスを取得します。
getChain	サーバーが接続しているチェーンの ID と名前を取得します。
getBalance	指定したアドレス（またはサーバーのウォレット）のネイティブトークン残高を取得します。
signMessage	サーバーに設定されているウォレットを使ってメッセージに署名します。
sendNativeToken	サーバーのウォレットから受取人にネイティブトークン（例：ETH）を送信します。
getTokenBalance	指定した所有者アドレスの ERC20 トークン残高を取得します。
transferToken	サーバーのウォレットから指定した数量の ERC20 トークンを送信します。
getTokenTotalSupply	ERC20 トークンの総供給量を取得します。
getTokenAllowance	ERC20 トークンについて、所有者が使用者に許可した使用限度額を取得します。
approveToken	使用者がサーバーのウォレットから ERC20 トークンを引き出せるよう許可します。
revokeApproval	ERC20 トークンについて、使用者の使用限度額を取り消し（0 に設定し）ます。
transferTokenFrom	あるアドレスから別のアドレスへ ERC20 トークンを送金します（事前の承認が必要です）。
convertToBaseUnit	10 進数のトークン数量を基準単位表現（例：wei）に変換します。
convertFromBaseUnit	基準単位表現のトークン数量を 10 進数の文字列に変換します。

（パラメーターと戻り値のスキーマの詳細は src/evm-tools.ts を参照してください）

🔒 セキュリティに関する考慮事項

• 秘密鍵の管理：WALLET_PRIVATE_KEY を設定ファイル（.cursor/mcp.json、claude_desktop_config.json）に直接埋め込んだり、.env ファイルを使用したりすると、セキュリティ上のリスクが生じます。**秘密鍵を含むファイルは、絶対にバージョン管理にコミットしないでください。**本番環境や高額資産を扱う場合は、専用のシークレット管理ソリューションを使用してください。 リスクを軽減するため、開発やテスト用に新しい専用のウォレット秘密鍵を作成することを強くおすすめします。ここでは、多額の資金を保有するメインウォレットの鍵を使用しないでください。
• RPC エンドポイントのセキュリティ：RPC_PROVIDER_URL が信頼できるノードを指していることを確認してください。
• アクセス制御：stdio モードで実行されるサーバーには、組み込みのアクセス制御がありません。サーバープロセスが実行される環境を保護してください。

📁 プロジェクト構成

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

💻 開発用スクリプト

package.json で定義されている主なスクリプト：

• pnpm run build：src/ 内の TypeScript コードを build/ 内の JavaScript にコンパイルします。
• pnpm run test：tsx を使ってテスト用クライアントの例（test/client.ts）を実行します。クライアントがサーバープロセスを自動的に起動します（.env が必要です）。
• pnpm run clean：build/ ディレクトリを削除します。
• pnpm run debug：デバッグ用に MCP Inspector を接続してサーバーを起動します（.env が必要です）。
• pnpm run prepublishOnly：npm への公開前にプロジェクトを自動的にクリーンアップし、ビルドします。

📄 ライセンス

このプロジェクトは MIT License の条件に基づいてライセンスされています。