EVM MCP Server

EVM MCP サーバー

複数の EVM 互換ネットワークでブロックチェーンサービスを提供する、包括的な Model Context Protocol（MCP）サーバーです。このサーバーにより、AI エージェントは統一されたインターフェースを通じて、Ethereum、Optimism、Arbitrum、Base、Polygon など、多数の EVM チェーンとやり取りできます。

📋 目次

• 概要
• 機能
• 対応ネットワーク
• 前提条件
• インストール
• サーバー設定
• 使い方
• API リファレンス
  • ツール
  • リソース
• セキュリティに関する考慮事項
• プロジェクト構成
• 開発
• ライセンス

🔭 概要

MCP EVM サーバーは、Model Context Protocol を活用して AI エージェントにブロックチェーンサービスを提供します。以下を含む幅広いサービスに対応しています。

• ブロックチェーンの状態（残高、トランザクション、ブロックなど）の読み取り
• スマートコントラクトとのやり取り
• トークンの送金（ネイティブ、ERC20、ERC721、ERC1155）
• トークンのメタデータと残高の照会
• 30 以上の EVM ネットワークに対応した、チェーン固有のサービス
• すべてのアドレスパラメーターでの ENS 名の解決（アドレスの代わりに「vitalik.eth」のような人間が読みやすい名前を使用できます）

すべてのサービスは、一貫した MCP ツールとリソースのインターフェースを通じて公開されているため、AI エージェントはブロックチェーン機能を簡単に見つけて利用できます。Ethereum アドレスを受け取るすべてのツールが ENS 名にも対応しており、裏側で自動的にアドレスへ解決します。

✨ 機能

ブロックチェーンデータへのアクセス

• 30 以上の EVM 互換ネットワークに対応
• チェーン情報（blockNumber、chainId、RPC など）
• ブロックデータを番号、ハッシュ、または最新のブロックで取得
• トランザクションの詳細と、デコード済みログを含むレシート
• アドレスの残高（ネイティブトークンおよびすべてのトークン規格）
• 人間が読みやすい Ethereum アドレスの ENS 解決（「0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045」の代わりに「vitalik.eth」を使用できます）

トークンサービス

• ERC20 トークン

  • トークンのメタデータ（名前、シンボル、小数桁数、供給量）の取得
  • トークン残高の確認
  • アドレス間でのトークン送金
  • 支出の許容量の承認

• NFT（ERC721）

  • コレクションとトークンのメタデータの取得
  • トークンの所有権の確認
  • アドレス間での NFT の送金
  • トークン URI と保有数の取得

• マルチトークン（ERC1155）

  • トークン残高とメタデータの取得
  • 数量を指定したトークンの送金
  • トークン URI へのアクセス

スマートコントラクトとのやり取り

• view/pure 関数によるコントラクト状態の読み取り
• 秘密鍵で署名する書き込みサービス
• EOA と区別するためのコントラクト検証
• イベントログの取得とフィルタリング

包括的なトランザクション対応

• 対応するすべてのネットワークでのネイティブトークンの送金
• トランザクション計画のためのガス見積もり
• トランザクションのステータスとレシート情報
• 説明的なメッセージによるエラー処理

🌐 対応ネットワーク

メインネット

• Ethereum（ETH）
• Optimism（OP）
• Arbitrum（ARB）
• Arbitrum Nova
• Base
• Polygon（MATIC）
• Polygon zkEVM
• Avalanche（AVAX）
• Binance Smart Chain（BSC）
• zkSync Era
• Linea
• Celo
• Gnosis（xDai）
• Fantom（FTM）
• Filecoin（FIL）
• Moonbeam
• Moonriver
• Cronos
• Scroll
• Mantle
• Manta
• Blast
• Fraxtal
• Mode
• Metis
• Kroma
• Zora
• Aurora
• Canto

テストネット

• Sepolia
• Optimism Sepolia
• Arbitrum Sepolia
• Base Sepolia
• Polygon Amoy
• Avalanche Fuji
• BSC Testnet
• zkSync Sepolia
• Linea Sepolia
• Scroll Sepolia
• Mantle Sepolia
• Manta Sepolia
• Blast Sepolia
• Fraxtal Testnet
• Mode Testnet
• Metis Sepolia
• Kroma Sepolia
• Zora Sepolia
• Celo Alfajores
• Goerli
• Holesky

🛠️ 前提条件

• Bun 1.0.0 以上
• Node.js 18.0.0 以上（Bun を使用しない場合）

📦 インストール

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

# Install dependencies with Bun
bun install

# Or with npm
npm install

⚙️ サーバー設定

サーバーでは、次のデフォルト設定が使用されます。

• デフォルトのチェーン ID：1（Ethereum Mainnet）
• サーバーのポート：3001
• サーバーのホスト：0.0.0.0（すべてのネットワークインターフェースからアクセス可能）

これらの値はアプリケーションにハードコードされています。変更が必要な場合は、次のファイルを編集してください。

• チェーン設定：src/core/chains.ts
• サーバー設定：src/server/http-server.ts

🚀 使用方法

npx を使う（インストール不要）

npx を使うと、インストールせずに MCP EVM Server を直接実行できます。

# 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

サーバーをローカルで実行する

stdio を使ってサーバーを起動します（CLI ツールへの埋め込み用）。

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

または、ウェブアプリケーション向けに SSE を使って HTTP サーバーを起動します。

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

サーバーに接続する

MCP 互換のクライアントであれば、どれでもこの MCP サーバーに接続できます。テストやデバッグには、MCP Inspector を使用できます。

Cursor から接続する

Cursor から MCP サーバーに接続する手順は次のとおりです。

1. Cursor を開き、設定（左下の歯車アイコン）に移動します

2. 左側のサイドバーで「Features」をクリックします

3. 「MCP Servers」セクションまでスクロールします

4. 「Add new MCP server」をクリックします

5. 次の詳細を入力します。

   • サーバー名：evm-mcp-server
   • 種類：command
   • コマンド：npx @mcpdotdirect/evm-mcp-server

6. 「Save」をクリックします

接続すると、Cursor 内で MCP サーバーの機能を直接使用できます。サーバーは MCP Servers の一覧に表示され、必要に応じて有効／無効を切り替えられます。

Cursor で mcp.json を使う

チームで共有したり、複数のプロジェクトで使ったりできる、よりポータブルな設定にするには、プロジェクトのルートディレクトリに .cursor/mcp.json ファイルを作成します。

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

このファイルをプロジェクトの .cursor ディレクトリに配置します（存在しない場合は作成してください）。Cursor はそのプロジェクトで作業する際に、これらの MCP サーバー設定を自動的に検出して使用します。この方法には、次のような利点があります。

1. MCP 設定をチームと共有する
2. MCP のセットアップをバージョン管理する
3. プロジェクトごとに異なるサーバー設定を使用する

例：SSE を使った HTTP モード

ウェブアプリケーションを開発していて、Server-Sent Events（SSE）を使って HTTP サーバーに接続する場合は、次の設定を使用できます。

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

これは HTTP サーバーの SSE エンドポイントに直接接続します。次のような場合に便利です。

• ブラウザーから MCP サーバーに接続する必要があるウェブアプリケーション
• ローカルコマンドの実行が適していない環境
• 複数のユーザーやアプリケーションで単一の MCP サーバーインスタンスを共有する場合

この設定を使用する手順は次のとおりです。

1. プロジェクトのルートに .cursor ディレクトリが存在しない場合は作成します
2. 上記の JSON を .cursor ディレクトリに mcp.json として保存します
3. Cursor を再起動するか、プロジェクトを開きます
4. Cursor が設定を検出し、サーバーを有効にするかどうかを確認します

例：Cursor で MCP サーバーを使う

mcp.json で MCP サーバーを設定すると、Cursor で簡単に利用できます。以下にワークフローの例を示します。

1. プロジェクトに新しい JavaScript／TypeScript ファイルを作成します。

// blockchain-example.js
async function main() {
  try {
    // Get ETH balance for an address using ENS
    console.log("Getting ETH balance for vitalik.eth...");

    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"

    // Cursor will use the MCP server to execute these operations
    // without requiring any additional code from you

    // This is the power of the MCP integration - your AI assistant
    // can directly interact with blockchain data and operations
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. Cursor でファイルを開いた状態で、次のように Cursor に依頼できます。

   • 「vitalik.eth の現在の ETH 残高を確認して」
   • 「Ethereum 上の USDC の価格を調べて」
   • 「Optimism の最新ブロックを表示して」
   • 「0x1234... がコントラクトアドレスかどうか確認して」

3. Cursor は MCP サーバーを使ってこれらの操作を実行し、結果を会話内に直接返します。

MCP サーバーがブロックチェーンとの通信をすべて処理するため、Cursor は自然言語を通じてブロックチェーン関連のタスクを理解し、実行できます。

Claude CLI を使って接続する

Claude CLI を使っている場合は、2 つのコマンドだけで MCP サーバーに接続できます。

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

# Start Claude with the MCP server enabled
claude

例：ENS を使ってトークン残高を取得する

// Example of using the MCP client to check a token balance using ENS
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
  ownerAddress: "vitalik.eth", // ENS name instead of address
  network: "ethereum",
});

console.log(result);
// {
//   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum",
//   raw: "1000000000",
//   formatted: "1000",
//   symbol: "USDC",
//   decimals: 6
// }

例：ENS 名を解決する

// Example of using the MCP client to resolve an ENS name to an address
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve-ens", {
  ensName: "vitalik.eth",
  network: "ethereum",
});

console.log(result);
// {
//   ensName: "vitalik.eth",
//   normalizedName: "vitalik.eth",
//   resolvedAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum"
// }

📚 API リファレンス

ツール

サーバーは、エージェント向けに以下の MCP ツールを提供します。アドレスパラメーターを受け付けるすべてのツールは、Ethereum アドレスと ENS 名の両方に対応しています。

トークンサービス

ツール名	説明	主なパラメーター
get-token-info	ERC20 トークンのメタデータを取得します	tokenAddress (アドレス/ENS)、network
get-token-balance	ERC20 トークンの残高を確認します	tokenAddress (アドレス/ENS)、ownerAddress (アドレス/ENS)、network
transfer-token	ERC20 トークンを送金します	privateKey、tokenAddress (アドレス/ENS)、toAddress (アドレス/ENS)、amount、network
approve-token-spending	トークンの利用上限を承認します	privateKey、tokenAddress (アドレス/ENS)、spenderAddress (アドレス/ENS)、amount、network
get-nft-info	NFT のメタデータを取得します	tokenAddress (アドレス/ENS)、tokenId、network
check-nft-ownership	NFT の所有権を確認します	tokenAddress (アドレス/ENS)、tokenId、ownerAddress (アドレス/ENS)、network
transfer-nft	NFT を送金します	privateKey、tokenAddress (アドレス/ENS)、tokenId、toAddress (アドレス/ENS)、network
get-nft-balance	所有している NFT の数を確認します	tokenAddress (アドレス/ENS)、ownerAddress (アドレス/ENS)、network
get-erc1155-token-uri	ERC1155 のメタデータを取得します	tokenAddress (アドレス/ENS)、tokenId、network
get-erc1155-balance	ERC1155 の残高を確認します	tokenAddress (アドレス/ENS)、tokenId、ownerAddress (アドレス/ENS)、network
transfer-erc1155	ERC1155 トークンを送金します	privateKey、tokenAddress (アドレス/ENS)、tokenId、amount、toAddress (アドレス/ENS)、network

ブロックチェーンサービス

ツール名	説明	主なパラメーター
get-chain-info	ネットワーク情報を取得します	network
get-balance	ネイティブトークンの残高を取得します	address (アドレス/ENS)、network
transfer-eth	ネイティブトークンを送信します	privateKey、to (アドレス/ENS)、amount、network
get-transaction	トランザクションの詳細を取得します	txHash、network
read-contract	スマートコントラクトの状態を読み取ります	contractAddress (アドレス/ENS)、abi、functionName、args、network
write-contract	スマートコントラクトに書き込みます	contractAddress (アドレス/ENS)、abi、functionName、args、privateKey、network
is-contract	アドレスがコントラクトかどうかを確認します	address (アドレス/ENS)、network
resolve-ens	ENS 名をアドレスに解決します	ensName、network

リソース

サーバーは、以下の MCP リソース URI を通じてブロックチェーンデータを公開します。アドレスを受け付けるすべてのリソース URI は ENS 名にも対応しており、アドレスに自動的に解決されます。

ブロックチェーンリソース

リソース URI パターン	説明
evm://{network}/chain	特定のネットワークのチェーン情報
evm://chain	Ethereum メインネットのチェーン情報
evm://{network}/block/{blockNumber}	番号で指定したブロックデータ
evm://{network}/block/latest	最新のブロックデータ
evm://{network}/address/{address}/balance	ネイティブトークンの残高
evm://{network}/tx/{txHash}	トランザクションの詳細
evm://{network}/tx/{txHash}/receipt	ログを含むトランザクションレシート

トークンリソース

リソース URI パターン	説明
evm://{network}/token/{tokenAddress}	ERC20 トークン情報
evm://{network}/token/{tokenAddress}/balanceOf/{address}	ERC20 トークンの残高
evm://{network}/nft/{tokenAddress}/{tokenId}	NFT（ERC721）トークン情報
evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}	NFT の所有権確認
evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri	ERC1155 トークン URI
evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}	ERC1155 トークンの残高

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

• 秘密鍵はトランザクションの署名にのみ使用され、サーバーに保存されることはありません
• 本番環境で使用する場合は、追加の認証メカニズムの実装を検討してください
• 本番環境では、HTTP サーバーに HTTPS を使用してください
• 不正利用を防ぐため、レート制限を実装してください
• 高額なサービスでは、確認手順の追加を検討してください

📁 プロジェクト構成

mcp-evm-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Operation exports
│   │       ├── balance.ts      # Balance services
│   │       ├── transfer.ts     # Token transfer services
│   │       ├── utils.ts        # Utility functions
│   │       ├── tokens.ts       # Token metadata services
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── transactions.ts # Transaction services
│   │       └── blocks.ts       # Block services
│   │       └── clients.ts      # RPC client utilities
├── package.json
├── tsconfig.json
└── README.md

🛠️ 開発

サーバーを変更または拡張するには、次の手順に従ってください。

1. src/core/services/ の適切なファイルに新しいサービスを追加します
2. src/core/tools.ts に新しいツールを登録します
3. src/core/resources.ts に新しいリソースを登録します
4. src/core/chains.ts に新しいネットワークのサポートを追加します
5. サーバーの設定を変更するには、src/server/http-server.ts のハードコードされた値を編集します

📄 ライセンス

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