hedera-mcp

hedera-mcp

Hedera（Hashgraph）向けの包括的な Model Context Protocol サーバーです。 Hedera のすべてのコアサービス（アカウント、トークン（HTS）、コンセンサス（HCS）、スマートコントラクト（EVM）、ファイル、スケジュール、ネットワーク）を網羅し、あらゆる AI エージェント（Claude、Cursor など）が呼び出せる 79 個の MCP ツールとして提供します。

ビルド専用。キーは保持しません。 読み取りにはパブリックの Mirror Node REST API を使用します（認証不要）。書き込みでは、署名してご自身のウォレット／SDK／CLI で送信するための、署名前の凍結済みトランザクション（base64）を返します。このサーバーが秘密鍵を参照したり、何かを実行したりすることはありません。

---

このサーバーが作られた理由

Hedera 公式の Agent Kit には、事前設定済みの MCP サーバーが含まれていますが、ツールの範囲は意図的に絞られています（残高、送金、デプロイ）。このサーバーは、開発者向けの学習とエージェント主導のオンボーディングに適した構成で、Hedera API をエンドツーエンドで網羅してその不足を補います。これにより、開発者は 1 回の AI セッションで「認定済み」の状態から「初めての HTS トークン／HCS トピック／コントラクトをリリースする」段階まで進めます。

サービス	公式スターター MCP	hedera-mcp
アカウント	残高	作成、送金、更新、削除、使用許可、情報、残高、NFT
トークン（HTS）	送金、デプロイ	FT／NFT の作成、ミント、バーン、送金、関連付け、凍結、KYC、一時停止、ワイプ、削除、情報
コンセンサス（HCS）	—	トピックの作成／更新／削除、メッセージの送信と読み取り
スマートコントラクト	—	デプロイ、実行、eth_call 読み取り、情報
ファイル	—	作成、追加、削除、情報
スケジュール	—	作成、署名、削除、情報
ネットワーク	—	トランザクション検索、ノード、手数料、供給量、為替レート、デコード

セキュリティモデル

• 読み取り → パブリックの Mirror Node REST を使用します。キーもアカウントも不要です。
• 書き込み → ツールがトランザクションを構築し、オフライン署名用に凍結して、人が読める概要とともに base64 バイト列を返します。内容を確認（hedera_decode_transaction）した後、ご自身で署名して送信します。
• 任意の環境変数は HEDERA_OPERATOR_ID のみです。これはアカウント IDで、構築時のデフォルトの支払者／トレジャリーとして使用されます。キーではありません。

この設計方針は goat-network-mcp に倣っています。どこで実行しても安全で、自律型エージェントに渡しても安全です。

npm と MCP Registry では、io.github.ExpertVagabond/hedera-mcp として公開されています。

インストール

npx で直接実行します（クローンは不要です）。

npx @purplesquirrel/hedera-mcp

または、ソースから実行します。

npm install
npm run build

設定（Claude Desktop／Claude Code）

{
  "mcpServers": {
    "hedera": {
      "command": "npx",
      "args": ["-y", "@purplesquirrel/hedera-mcp"],
      "env": {
        "HEDERA_NETWORK": "testnet",
        "HEDERA_OPERATOR_ID": "0.0.1234"
      }
    }
  }
}

環境変数	デフォルト	備考
HEDERA_NETWORK	testnet	mainnet | testnet | previewnet
HEDERA_OPERATOR_ID	(未設定)	デフォルトの支払者／トレジャリーとして使用する任意のアカウント ID（キーではありません）
HEDERA_MIRROR_URL	ネットワークごと	Mirror Node REST のベース URL を上書きします（例：プライベートノード／HGraph ノード）

ビルド専用のワークフロー

agent calls hedera_create_fungible_token
        │
        ▼
hedera-mcp builds + freezes the TokenCreateTransaction
        │
        ▼
returns base64 (unsigned)  ──►  you sign in HashPack / SDK / CLI  ──►  submit to Hedera

署名前にすべての内容を確認できます。

hedera_decode_transaction { transactionBase64: "<bytes>" }
→ { type: "TokenCreateTransaction", transactionId, nodeAccountIds, maxTransactionFee, ... }

ツールカタログ（79）

アカウント（8）： create_account · transfer_hbar · update_account · delete_account · approve_hbar_allowance · get_account_info · get_account_balance · get_account_nfts

トークン / HTS（23）： create_fungible_token · create_nft_collection · mint_fungible · mint_nft · burn_token · transfer_token · transfer_nft · associate_token · dissociate_token · freeze_token_account · unfreeze_token_account · grant_kyc · revoke_kyc · pause_token · unpause_token · wipe_token · delete_token · update_token · token_airdrop · reject_token · approve_token_allowance · approve_nft_allowance · get_token_info · get_nft_info

コンセンサス / HCS（6）： create_topic · submit_message · update_topic · delete_topic · get_topic_info · get_topic_messages

スマートコントラクト / EVM（6）： deploy_contract · execute_contract · update_contract · delete_contract · query_contract · get_contract_info — execute_contract と query_contract は ABI 対応です（{ abi, functionName, args } を渡すと、calldata のエンコードと結果のデコードが自動的に行われます）

ファイル（4）： create_file · append_file · update_file · delete_file

スケジュール（4）： create_schedule · sign_schedule · delete_schedule · get_schedule_info

ネットワーク / ユーティリティ（7）： prng · get_transaction · get_network_nodes · get_exchange_rate · get_network_supply · get_network_fees · decode_transaction

分析（Mirror Node の読み取り、14）： get_block · get_blocks · get_account_transactions · get_token_balances · get_token_nfts · get_nft_history · get_account_allowances · get_account_token_allowances · get_account_nft_allowances · get_contract_results · get_contract_state · get_network_stake · search_accounts_by_pubkey · get_account_by_evm

リソース（4）

ツールに加えて、サーバーは URI で読み取り可能な、アドレス指定可能でキー不要の MCP リソースをエージェントに提供します。

hedera://network/exchange-rate · hedera://network/supply · hedera://account/{accountId} · hedera://token/{tokenId}

例と学習

• examples/TUTORIAL.md — 5 つのプロンプトで Hedera 上に構築する（認定から出荷までの学習パス）
• examples/agent-demo.md — Claude Desktop に接続し、質問しながら構築します。node examples/agent-sim.mjs を実行すると、再現可能なエージェントのトランスクリプトが出力されます
• examples/scenarios/ — 独自のユースケースです。それぞれ実行可能で、Mirror Node による検証に対応しています：HCS 公証人、AI エージェントの監査証跡、エージェント間決済、自己課税トークン

検証

• npm run lint / npm run build — @hashgraph/sdk 2.81.0 に対して問題なく完了
• node test-battle.mjs — 自動検出スイートで 72/73（スキップ 1 件：query_contract は既知の ABI が必要なため、別途検証済み）→ 全 73 ツールを検証済み（MPP 導入前。MPP 課金ツールを含めると 79）
• node test-live.mjs — テストネットで 10/10 の書き込みパスを実行し、Mirror Node で検証済み
• node test-battle-live.mjs — バトルモード：テストネットで 2 つのアカウントを使って 31/31 の操作を実行（フリーズ／KYC／一時停止／ワイプを含むトークンの全ライフサイクル、NFT、トピック、ファイル、2 人目の署名者が必要なスケジュール済み送金、PRNG）。Mirror Node で検証済み。ED25519 オペレーターによる署名で再実行しても 31/31 のまま成功 — EVM 以外のツールは鍵の種類に依存しません（サーバーは鍵を保持しません。Hedera の EVM エイリアスルールにより、EVM ツールには ECDSA が必須です）
• node test-contract.mjs — 実際の Solidity コントラクトをエンドツーエンドでコンパイル → デプロイ → 実行 → 読み取り（store(42) → retrieve() = 42）し、EVM パス全体と query_contract を確認
• node test-contract-abi.mjs — ABI 対応の query_contract：生の ABI を渡すと、自動でエンコード／デコードします — answer() → 73（uint）、title() → "hedera-mcp"（string）、ping() → 73（pure）
• node test-edge-cases.mjs — テストネットで 12/12 のエッジケースパスを検証。通常の成功パスのスイートでは見落とされるケース：create+append による大容量ファイル（1 トランザクションのチャンクを超過）、1024 B を超える HCS メッセージを 2 つのミラーエントリーに自動分割（再構成後 1200 B）、ロイヤルティ 10% と 1ℏ のフォールバックカスタム手数料を設定した NFT コレクション、委任された承認済み支出（オペレーターが B を承認 → B が自身の手数料を支払って 200 を引き出し）、新規 ED25519 エイリアスへの HBAR 送金による自動アカウント作成、decode_transaction の往復処理

開発

npm run lint       # tsc --noEmit
npm run build      # compile to dist/
node test-smoke.mjs    # MCP stdio: live Mirror Node read + build-only write + decode
node demo.mjs          # narrated "developer's first session" walkthrough (build-only)
node test-execute.mjs  # LIVE testnet submit (needs a throwaway key in .env — see below)

ライブ実行の検証

test-execute.mjs は、ビルドのみの出力が実際に動作することを証明します。MCP サーバーが 未署名のトランザクションを作成し、ハーネスが .env の使い捨てテストネット鍵で 署名して送信した後、Mirror Node を通じて結果を独立して確認します。サーバーは 全工程を通じてビルドのみの状態を維持し、鍵に触れるのはテストハーネスだけです。

HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.xxxxxx
HEDERA_OPERATOR_KEY=302e0201...    # rotate/discard after verifying

portal.hedera.com で無料のテストネットアカウントを取得できます。

@hashgraph/sdk と @modelcontextprotocol/sdk を基盤として構築されています。

リリース

package.json、server.json（最上位の version と packages[0].version の両方）、および src/index.ts のバージョンを更新し、CHANGELOG.md を更新した後、npm と MCP Registry に公開します。

npm run build
npm publish --access public

続いて、MCP Registry と同期します。mcp-publisher はプロジェクトディレクトリではなく /tmp から実行してください — この環境ではプロジェクトが、パブリッシャーが OAuth トークンを保存できないボリューム上にあります（operation not permitted）。そのため、公開手順がエラーを表示せずに失敗します。server.json を書き込み可能な一時ディレクトリにコピーすれば回避できます。

mkdir -p /tmp/hedera-publish
cp server.json /tmp/hedera-publish/
cd /tmp/hedera-publish
mcp-publisher login github      # device-code flow, authorize as ExpertVagabond
mcp-publisher publish

以下の 3 つすべてで整合性が取れていることを確認します。

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=ExpertVagabond/hedera-mcp&version=latest" | jq '.servers[0].server | {name, version}'
npm view @purplesquirrel/hedera-mcp version

ライセンス

MIT © Matthew Karsten