Starknet MCP Server

Starknet MCP Server

Starknet ブロックチェーン向けの包括的な Model Context Protocol（MCP）サーバーです。このサーバーにより、AI エージェントは Starknet ネットワークとやり取りし、ブロックチェーンデータを照会し、ウォレットを管理し、スマートコントラクトとやり取りできます。

📋 目次

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

🔭 概要

Starknet MCP Server は、Model Context Protocol を活用して AI エージェントにブロックチェーンサービスを提供します。Starknet エコシステムへの包括的なインターフェースを備え、自然言語を通じて Starknet のブロックチェーンデータや操作とやり取りする機能を AI アシスタントに提供します。

主な機能は次のとおりです。

• ブロックチェーンの状態の読み取り（残高、トランザクション、ブロック）
• Cairo スマートコントラクトとのやり取り
• トークンの転送（ETH、STRK、その他の ERC20 トークン）
• NFT およびトークンのメタデータの操作
• StarknetID ドメインの解決（Ethereum の ENS に相当）
• 適切なトランザクション処理による読み取り操作と書き込み操作

すべてのサービスは、統一された MCP ツールとリソースのインターフェースを通じて公開されるため、AI エージェントは Starknet ブロックチェーンの機能を簡単に見つけて利用できます。Starknet アドレスを受け取るすべてのツールは StarknetID にも対応しており、人が読みやすい ID をバックグラウンドで自動的にアドレスに解決します。

✨ 機能

• Starknet 連携：Starknet.js を使用した Starknet ブロックチェーンとの完全な連携
• ネットワーク対応：Mainnet と Sepolia テストネットの両方に対応
• StarknetID 連携：Starknet ID とアドレスを相互に解決
• ネイティブトークン対応：ETH と STRK のネイティブトークンに対応
• スマートコントラクトとのやり取り：Starknet スマートコントラクトの呼び出しと照会
• デュアルトランスポート：用途に応じて stdio サーバーまたは HTTP サーバーとして実行
• AI 対応：Claude、GPT、その他の AI アシスタントでの使用を想定した設計

ブロックチェーン情報

• チェーン情報（チェーン ID、最新ブロック）の照会
• ブロックの詳細とトランザクションの確認
• トランザクションのレシートとステータスの表示
• アドレス情報とコントラクトデータの取得

ネイティブトークン操作

• 任意のアドレスの ETH と STRK の残高を取得
• アカウント間で ETH と STRK を転送
• ネイティブトークンの合計残高を表示

トークン操作

• ERC20 トークンの残高と情報を取得
• ERC20 トークンを転送
• トークンの供給量とメタデータを表示
• トークンの所有権を確認

NFT 操作

• トークン ID による NFT の所有権確認
• NFT コレクション情報の取得
• アドレスごとの NFT 残高の表示

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

• 読み取り専用のコントラクト関数を呼び出す
• トランザクション確認を伴うコントラクトへの書き込みを実行
• コントラクトのストレージ情報を取得
• ABI とコントラクトクラス情報を表示

StarknetID

• Starknet アドレスを Starknet ID に解決します
• Starknet ID をアドレスに解決します
• 検証データを含む Starknet ID の完全なプロフィールを取得します
• Starknet ドメインを検証します

🔧 対応ネットワーク

サーバーは次の Starknet ネットワークに対応しています。

• Mainnet：Starknet の主要な本番ネットワーク
• Sepolia：Ethereum の Sepolia 上にある Starknet のテストネット

🛠️ 前提条件

• Bun 1.0.0 以降（推奨）
• Node.js 18.0.0 以降

📦 インストール

Smithery 経由でのインストール

Smithery 経由で starknet-mcp-server をインストールし、Claude Desktop に自動的に設定するには：

npx -y @smithery/cli install @mcpdotdirect/starknet-mcp-server --client claude

オプション 1：インストールせずに使用する（npx）

最も簡単に始めるには、npx を使ってパッケージを直接実行します。

# Run the stdio server without installation
npx @mcpdotdirect/starknet-mcp-server

# Run the HTTP server without installation
npx @mcpdotdirect/starknet-mcp-server http

インストールする必要はなく、最新バージョンが自動的にダウンロードされて実行されます。

オプション 2：グローバルインストール

頻繁に使用する場合は、グローバルにインストールできます。

# Install globally
npm install -g @mcpdotdirect/starknet-mcp-server

# Then run from anywhere
starknet-mcp-server
starknet-mcp-server http

オプション 3：ローカルプロジェクトへのインストール

# Add to your project
npm install @mcpdotdirect/starknet-mcp-server

# Using yarn
yarn add @mcpdotdirect/starknet-mcp-server

# Using pnpm
pnpm add @mcpdotdirect/starknet-mcp-server

次に、package.json のスクリプトに追加します。

"scripts": {
  "starknet-mcp": "starknet-mcp-server",
  "starknet-mcp-http": "starknet-mcp-server http"
}

オプション 4：ソースから実行する

ソースから実行する場合や、ローカルで開発する場合：

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

# Install dependencies
npm install

# Start the stdio server
npm start

# Or start the HTTP server
npm run start:http

自動リロードを有効にして開発する場合：

# Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

⚙️ サーバー設定

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

• デフォルトネットワーク：Mainnet
• サーバーポート：3000（HTTP モード）
• サーバーホスト：0.0.0.0（すべてのネットワークインターフェースからアクセス可能）

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

• ネットワーク設定：src/core/chains.ts
• サーバー設定：src/server/http-server.ts

🔍 使用方法

サーバーの実行

Starknet MCP Server は次の 2 つのモードで実行できます。

# Run the server in stdio mode (for CLI tools and AI assistants)
npx @mcpdotdirect/starknet-mcp-server

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

HTTP サーバーはデフォルトでポート 3000 で動作し、リアルタイム通信のための REST API と Server-Sent Events（SSE）の両方を提供します。

Cursor からの接続

Cursor から Starknet MCP サーバーに接続するには：

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

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

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

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

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

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

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

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

Cursor で mcp.json を使用する

チームと共有したり、複数のプロジェクトで使用したりできる、より移植性の高い設定にするには、プロジェクトのルートディレクトリに .cursor/mcp.json ファイルを作成します。

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

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

SSE を使用する HTTP モード

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

{
  "mcpServers": {
    "starknet-mcp-sse": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude CLI を使用した接続

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

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

# Start Claude with the MCP server enabled
claude

例：Cursor で MCP サーバーを使用する

MCP サーバーを設定すると、Cursor で簡単に使用できます。たとえば：

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

// starknet-example.js
async function main() {
  try {
    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 on Starknet mainnet"
    // Or "Lookup the Starknet ID for address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
    
    // Cursor will use the MCP server to execute these operations 
    // without requiring any additional code from you
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. Cursor でファイルを開いた状態で、次のように Cursor に依頼できます。
   • 「vitalik.stark の ETH 残高を確認して」
   • 「Starknet の最新ブロックに関する情報を取得して」
   • 「コレクション 0x... の NFT #123 の所有者を調べて」

例：Starknet ID を使用した ETH 残高の取得

// Example of using the MCP client to check an ETH balance using Starknet ID
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get_starknet_eth_balance", {
  address: "vitalik.stark", // Starknet ID instead of address
  network: "mainnet"
});

console.log(result);
// {
//   wei: "1000000000000000000",
//   ether: "1.0"
// }

例：Starknet ID の解決

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

const result = await mcp.invokeTool("resolve_starknet_address", {
  name: "vitalik.stark",
  network: "mainnet"
});

console.log(result);
// {
//   starknetId: "vitalik.stark",
//   address: "0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d",
//   resolved: true
// }

例：スマートコントラクトの呼び出し

// Example of using the MCP client to call a smart contract function
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("call_starknet_contract", {
  contractAddress: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH contract
  entrypoint: "totalSupply",
  calldata: [],
  network: "mainnet"
});

console.log(result);
// {
//   result: ["0x84b6c7d5970d5a73abe"]
// }

Node.js プロジェクトでの使用

Node.js プロジェクトで MCP サーバーをプログラムから使用する場合：

// Start the MCP server as a child process
const { spawn } = require('child_process');
const mcpServer = spawn('npx', ['@mcpdotdirect/starknet-mcp-server']);

// Connect to it with the MCP client
const mcp = new McpClient({ process: mcpServer });

// Now you can use the client
const networks = await mcp.invokeTool("get_supported_starknet_networks", {
  random_string: "any"
});
console.log("Supported networks:", networks);

より高度な使い方として、HTTP API をラップするクラスを作成するか、Axios などのライブラリを使用すると、よりすっきりした API 呼び出しができます。

📚 API リファレンス

利用可能な MCP ツール

このサーバーでは、以下の MCP ツールを実装しています。

ネットワークツール

• get_starknet_chain_info：Starknet ネットワークの情報を取得します
• get_supported_starknet_networks：サポートされている Starknet ネットワークの一覧を取得します

残高ツール

• get_starknet_eth_balance：Starknet アドレスまたは Starknet ID の ETH 残高を取得します
• get_starknet_token_balance：アドレスの任意のトークン残高を取得します
• get_starknet_strk_balance：アドレスの STRK トークン残高を取得します
• get_starknet_native_balances：アドレスのすべてのネイティブトークン残高（ETH および STRK）を取得します

StarknetID ツール

• resolve_starknet_name：アドレスに対応する Starknet ID を取得します
• resolve_starknet_address：Starknet ID に対応するアドレスを取得します
• get_starknet_profile：アドレスの Starknet ID プロフィール全体を取得します
• validate_starknet_domain：文字列が有効な Starknet ID かどうかを確認します

ブロックツール

• get_starknet_block：特定のブロックの情報を取得します
• get_starknet_block_transactions：特定のブロック内のトランザクションを取得します

トランザクションツール

• get_starknet_transaction：トランザクションの詳細を取得します
• get_starknet_transaction_receipt：トランザクションのレシートを取得します
• check_starknet_transaction_status：トランザクションが確定しているかどうかを確認します

コントラクトツール

• call_starknet_contract：コントラクトの読み取り専用関数を呼び出します
• get_starknet_contract_class：コントラクトのクラス（ABI などの情報）を取得します
• execute_starknet_contract：コントラクトの呼び出しを実行します（書き込み操作）

トークンツール

• get_starknet_token_info：トークンの情報を取得します
• get_starknet_token_supply：トークンの総供給量を取得します
• check_starknet_nft_ownership：アドレスが特定の NFT を所有しているかどうかを確認します
• get_starknet_nft_balance：アドレスが所有する NFT の数を取得します

送金ツール

• transfer_starknet_eth：あるアカウントから別のアカウントに ETH を送金します（金額は人が読みやすい形式です）
• transfer_starknet_strk：あるアカウントから別のアカウントに STRK を送金します（金額は人が読みやすい形式です）
• transfer_starknet_token：あるアカウントから別のアカウントに ERC20 トークンを送金します（金額は人が読みやすい形式です）

利用可能な MCP リソース

このサーバーでは、以下の MCP リソースを提供しています。

ネットワークリソース

• starknet://{network}/chain：特定のネットワークのチェーン情報を取得します
• starknet://networks：サポートされているすべてのネットワークの一覧を取得します

ブロックリソース

• starknet://{network}/block/{blockIdentifier}：特定のブロックの情報を取得します
• starknet://{network}/block/latest：最新のブロックを取得します

アドレスリソース

• starknet://{network}/address/{address}：アドレスの情報を取得します

トランザクションリソース

• starknet://{network}/tx/{txHash}：トランザクション情報を取得します

StarknetID リソース

• starknet://{network}/id/address/{address}：アドレスを Starknet ID に解決します
• starknet://{network}/id/name/{name}：Starknet ID をアドレスに解決します
• starknet://{network}/id/profile/{address}：アドレスの Starknet ID プロフィールを取得します

利用可能な MCP プロンプト

LLM との対話用に、このサーバーでは以下のプロンプトを提供しています。

• explore_starknet_block：特定の Starknet ブロックの情報を調べます
• explore_starknet_address：Starknet アドレスの情報を取得します
• explore_starknet_transaction：Starknet トランザクションの情報を取得します
• lookup_starknet_id：Starknet ID を検索するか、アドレスを Starknet ID に解決します
• explore_starknet_id_profile：Starknet ID プロフィール全体を調べます

🔍 AI アシスタントでの使用方法

このサーバーを Claude や GPT などの AI アシスタントと使用する場合：

1. MCP サーバーを使用するように AI アシスタントを設定します
2. その後、アシスタントはツールを使用して Starknet とやり取りできます
3. クエリの例：
   • 「アドレス 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d の ETH 残高はいくらですか？」
   • 「アドレス 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d の Starknet ID を調べてください」
   • 「Starknet メインネットの最新ブロックには何が含まれていますか？」
   • 「トランザクション 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198 の情報を取得してください」
   • 「Starknet ID の vitalik.stark をアドレスに解決してください」

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

• 秘密鍵はトランザクションの署名にのみ使用され、サーバーに保存されることはありません
• すべてのトークン数量は、wei や最小単位ではなく、人が読み取れる形式（例：ETH、STRK、トークン単位）で指定します
• 操作を実行する前に、入力パラメーターを必ず検証し、サニタイズしてください
• 本番環境で使用する場合は、追加の認証メカニズムの実装を検討してください
• 本番環境では、HTTP サーバーに HTTPS を使用してください
• 不正使用を防ぐため、レート制限を実装してください
• 高額なサービスでは、確認手順の追加を検討してください

📁 プロジェクト構成

starknet-mcp-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        # Service exports
│   │       ├── balance.ts      # Balance services
│   │       ├── blocks.ts       # Block services
│   │       ├── clients.ts      # Client utilities
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── starknetid.ts   # Starknet ID services
│   │       ├── tokens.ts       # Token services
│   │       ├── transactions.ts # Transaction services
│   │       ├── transfer.ts     # Transfer services
│   │       └── utils.ts        # Utility functions
├── package.json
├── tsconfig.json
└── README.md

🛠️ 開発規約

カスタムツール、リソース、プロンプトを追加する場合：

1. すべてのリソース名、ツール名、プロンプト名で、ハイフン（-）の代わりにアンダースコア（_）を使用します

   // Good: Uses underscores
   server.tool(
     "starknet_contract_call",
     "Description of the tool",
     {
       contract_address: z.string().describe("The contract address")
     },
     async (params) => {
       // Tool implementation
     }
   );
   

2. この命名規約により、Cursor やその他の AI ツールとの互換性が確保されます

📚 ドキュメント

詳しくは、以下をご覧ください：

• Model Context Protocol
• Starknet.js ドキュメント
• Starknet ドキュメント
• StarknetID ドキュメント

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。