NEAR Protocol Full-Featured MCP Server

NEAR Protocol の全機能対応 MCP サーバー

このプロジェクトは、NEAR Protocol ブロックチェーンと連携するための Model Context Protocol（MCP）サーバーを実装します。MCP クライアント（Claude Desktop など）経由で接続した大規模言語モデル（LLM）が、ブロックチェーンデータを照会し、事前設定された NEAR アカウントを使用してトランザクションを実行できます。

⚠️ セキュリティに関する警告： このサーバーは、環境変数（MNEMONIC）に保存されたニーモニックシードフレーズを使って、トランザクション署名用の秘密鍵を導出します。この方法は本番環境では安全ではありません。重要な価値を保有していないアカウントを使ったローカルでの開発とテストに限り、このサーバーを使用してください。本番環境では、より安全な鍵管理ソリューション（KMS、HSM、専用のシークレットマネージャーなど）を導入してください。

✨ 機能

このサーバーは、次の機能を MCP ツールとして公開します。

• get_account_balance：指定したアカウント（指定がない場合はサーバーのアカウント）の合計残高、ステーキング済み残高、状態ステーキング済み残高、利用可能残高を取得します。
• view_account_state：指定したコントラクトアカウント（指定がない場合はサーバーのアカウント）に保存されているキーと値の生の状態を表示します。オプションで、base64 エンコードされたキーのプレフィックスによるフィルタリングに対応しています。
• get_account_details：指定した NEAR アカウント（指定がない場合はサーバーのアカウント）の、残高やストレージ使用量などの詳細情報を取得します。
• create_sub_account：サーバーのアカウントの下に新しいサブアカウントを作成します。サフィックス、公開鍵、初期残高の指定が必要です。
• delete_account：サーバーのアカウントを削除し、残高を受益者に送金します。取り消しできない操作です！
• send_tokens：サーバーのアカウントから別のアカウントに NEAR トークンを送金します。
• call_function：指定したスマートコントラクト（指定がない場合はサーバーのアカウント）で変更メソッド（関数呼び出し）を実行し、必要に応じてガスとデポジットを付与します。
• batch_actions：特定の受信先を指定して、1 つのトランザクション内で複数のアクションをアトミックに実行します（指定がない場合はサーバーのアカウントが対象です）。
• deploy_contract：サーバーに設定されたアカウントに WASM スマートコントラクトをデプロイします。base64 エンコードされた WASM バイトコードが必要です。
• view_function：指定したコントラクト（指定がない場合はサーバーのアカウント）で読み取り専用関数を呼び出します。状態は変更されず、多くのガスも消費しません。
• get_access_keys：サーバーに設定されたアカウントに関連付けられたすべてのアクセスキー（公開鍵、権限、nonce）を一覧表示します。
• add_full_access_key：サーバーのアカウントにフルアクセス権限を持つ新しい鍵を追加します。
• add_function_call_key：サーバーのアカウントに、制限付きの関数呼び出し権限（特定のコントラクト、メソッド、許可額）を持つ新しい鍵を追加します。
• delete_access_key：サーバーのアカウントから既存のアクセスキーを削除します。
• verify_signature：指定した公開鍵に対して、メッセージの署名が有効かどうかを検証します。

🚀 前提条件

• Node.js： バージョン 16 以降。（ダウンロード）
• npm（通常は Node.js に付属）
• NEAR アカウント（任意）： 既存の NEAR アカウント（testnet または mainnet など）と、その12 語または 24 語のニーモニックシードフレーズを使用できます。アカウントが存在しない場合、サーバーはシードフレーズから導出された暗黙的アカウントを使用します。
• NEAR ネットワーク： 接続先の networkId（testnet、mainnet）を把握していること。
• （任意）MCP クライアント： Claude for Desktop など、MCP サーバーに接続できるアプリケーション。

🛠️ インストールとセットアップ

npm install near-mcp-server

1. 環境変数を設定します： プロジェクトのルートに .env ファイルを作成します。重要： シークレットのシードフレーズを誤ってコミットしないよう、.env を .gitignore ファイルに追加してください。

   # .env
   # 実際の12語または24語のシードフレーズに置き換えてください（引用符は不要です）
   MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
   
   # 'testnet' または 'mainnet' に設定します
   NEAR_NETWORK_ID="testnet"
   
   # 必要に応じて、別のRPCノードURLを指定します（省略可）
   # NEAR_NODE_URL="https://rpc.testnet.near.org"
   

2. サーバーをビルドします： TypeScriptコードをJavaScriptにコンパイルします。

   npm run build
   

   コンパイル済みの index.js ファイルを含む build ディレクトリが作成され、実行可能になります。

🏃 サーバーの実行

サーバーは、いくつかの方法で実行できます。

• npm startを使用する場合：

  npm start
  

• Nodeで直接実行する場合：

  node build/index.js
  

• バイナリ名を使用する場合（リンク済み、またはグローバルにインストールされている場合）：

  near-mcp-server-full
  

初期化に成功すると、サーバーは接続情報をstderrに出力します： Connected to NEAR <networkId> as <accountId> NEAR MCP Server running on stdio...

クライアントでサーバーを使用している間は、ターミナルを起動したままにしてください。サーバーのログとエラーは、このターミナルに表示されます（stderr）。

🔑 デフォルトのアカウント動作

このサーバーの実装では、アカウントIDを次のように処理します。

1. アカウントIDがツール関数に明示的に渡された場合（例：get_account_balance({ accountId: "example.near" })）、そのアカウントが使用されます。

2. アカウントIDが渡されない場合、サーバー自身のアカウント（MNEMONICから導出されたアカウント）が使用されます。

3. サーバーに確定したアカウントIDがない場合（例：シードフレーズに対応するアカウントがまだチェーン上に存在しない場合）、シードフレーズの公開鍵から導出された暗黙的なアカウントIDが使用されます。

この動作により、明示的に指定したアカウントとサーバー自身のアカウントの両方でツールをシームレスに使用でき、ユーザー体験が向上します。

🔌 クライアントへの接続（例：Claude Desktop）

1. Claudeの設定ファイルを探します： Claude Desktopの設定ファイルを見つけます。

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json （ファイルが存在しない場合は作成してください）。

2. 設定を編集します： mcpServers の下に、このサーバーのエントリを追加します。プロジェクトディレクトリ内のコンパイル済み build/index.js ファイルへの絶対パスを使用してください。

   {
     "mcpServers": {
       "near-protocol-server": {
         "command": "node",
         "args": [
           "/path/to/your/project/near-mcp-server/build/index.js"
         ]
         "env": {
           "MNEMONIC": "...",
           "NEAR_NETWORK_ID": "testnet"
         }
       }
     }
   }
   

3. Claudeを再起動します： 設定ファイルを保存し、Claude Desktopアプリケーションを完全に再起動します。

4. 接続を確認します： チャット入力欄にハンマーアイコンが表示されていることを確認します。クリックすると、このサーバーで定義されたNEARツールが一覧表示されます。

💬 使用例（Claude Desktop の場合）

接続すると、Claude に NEAR ツールを使用するよう依頼できます。

• What's the balance of my account?（サーバーのアカウントを使用します）
• What's the balance of vitalik.near?（アカウントを指定します）
• Get the account details for vitalik.near
• View the state for contract guest-book.testnet
• Send 0.1 NEAR from my account to friend.testnet
• Call the 'add_message' function on 'guest-book.testnet' with arguments {"text": "Hello from MCP!"}
• Call the 'set_greeting' function on my contract with arguments {"message": "Hello"}
• Deploy this contract (provide base64 WASM) to my account
• Create a subaccount 'mysub' under my account with public key 'ed25519:...' and fund it with 0.5 NEAR
• Show me all access keys for my account
• Add a full access key 'ed25519:...' to my account
• Delete the access key 'ed25519:...' from my account
• Delete my account and send the funds to 'beneficiary.testnet' (極めて慎重に実行してください！)
• Verify the message "test message" against signature "base64..." using public key "ed25519:..."
• Execute these actions in a batch for my account: transfer 0.1 NEAR to bob.testnet, then call method 'increase' on counter.testnet

Claude は適切なツールを特定し、状態を変更したり資金を使用したりするトランザクションを実行する前に、確認を求めます。

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

• 秘密鍵（ニーモニック）： シードフレーズを .env に保存する方法は、ローカルでのテスト以外では安全ではありません。実際の価値を保有するアカウントには、この方法を使用しないでください。本番環境でのユースケースでは、ハードウェアウォレット、セキュアエンクレーブソリューション、または KMS の利用を検討してください。.env ファイルが .gitignore に含まれていることを確認してください。
• 暗黙的なアカウント： リクエストでアカウント ID が明示的に指定されていない場合、サーバーは自身のアカウント ID を使用します。サーバーに既存のアカウント ID がない場合は、シードフレーズから導出された暗黙的なアカウントを使用します。
• ツールの権限： このサーバーは、接続された LLM クライアントに強力な機能を提供します。接続するクライアント、特に delete_account、add_full_access_key、deploy_contract などのツールには注意してください。
• 入力のサニタイズ： Zod は基本的な型検証を提供しますが、機密性の高い操作（コントラクト呼び出しや、拡張した場合のファイルパスなど）で使用するユーザーまたは LLM 提供の入力が適切にサニタイズされていることを確認してください。
• レート制限： 本番環境のサーバーでは、不正利用を防ぐためにレート制限の追加を検討してください。

🧪 開発

# Build the TypeScript code
npm run build

# Check TypeScript errors
npm run check-index

# Run in development mode (build + start)
npm run dev

🔧 トラブルシューティング

• サーバーが起動しない： npm start を実行したターミナルでエラーを確認してください。.env のすべての環境変数が正しく設定されていることを確認してください。Node.js v16+ がインストールされていることを確認してください。
• クライアント（Claude）に表示されない：
  • claude_desktop_config.json の構文を再確認してください。
  • build/index.js への絶対パスが正しいことを確認してください。
  • Claude Desktop を完全に再起動してください。
  • Claude の MCP ログを確認してください。
• ツールのエラー： near-api-js または NEAR ネットワークからの具体的なエラーメッセージについて、サーバーのターミナル出力（stderr）を確認してください。よくある問題には、残高不足、アカウント ID の誤り、ネットワークの問題などがあります。

🤝 貢献

貢献を歓迎します！ご提案や改善点がある場合は、issue を作成するか、プルリクエストを送信してください。

📜 ライセンス

MIT