Symbol (XYM)

symbol-mcp-server

Symbol 専用です。 このサーバーは Symbol（catapult）ノードと通信します。別のチェーンであり、異なる API を使用する NEM NIS1（XEM）には対応していません。 非公式です。 NEM または Symbol のコアチームとは無関係な独立プロジェクトです。

日本語版 README

Symbol REST API をタスク単位の 20 個のツールに変換する、読み取り専用の MCP サーバーです。REST エンドポイントを 1 対 1 で再現するのではなく、各ツールは実際に人が尋ねる質問に答えます。

• アカウント保有者： エイリアス名と小数桁を適用した残高、デコード済みメッセージ付きのトランザクション履歴と詳細、モザイクとネームスペースの検索、手数料の見積もり、アドレスの検証、高さ／エポック／時刻の変換。
• ノード運用者： ノードの健全性と同期状態、委任ハーベスティングの状態、参照ノードとの比較、そして何より 投票キーの有効期限：残りのエポック数、ブロック数、日数、推定有効期限、おすすめの更新期間。

すべてのツールは、公開された outputSchema に照らして検証される structuredContent と、同じ内容の JSON をテキストとして返します（ただし symbol_harvesting_income で output: "csv" を指定した場合は、代わりにテキストで CSV を返します）。最初に短い summary があり、1 行目で質問に答え、以降の行で各月や、問題のあるチェックなどの詳細を追加します。金額は小数桁を適用した値と生の整数値の両方で返されます。タイムスタンプは ISO 8601 UTC 形式で、SYMBOL_TIMEZONE が設定されている場合は現地時刻も追加されます。

表示例

2 回の呼び出しと、返される内容の抜粋です。値はライブノードではなく、テスト用フィクスチャ（合成されたノードホストとアカウント）から取得しています。

「ノードは正常で、同期していますか？」 → symbol_node_status {}

{
  "summary": "node.test:3001 (friendlyName \"fixture-node\", host \"mainnet-node.example\") on mainnet is healthy and synced.\nSymbol 1.0.3.9, roles Peer/API/Voting; height 5,763,675, finalized 5,763,656 (epoch 4004); 6 peers; latest block 201 s old (not synced above 300 s).",
  "verdict": "healthy",
  "sync": {
    "synced": true,
    "latestBlockTime": { "utc": "2026-09-10T03:01:38.808Z" },
    "ageSeconds": 201,
    "thresholdSeconds": 300,
    "checkedAt": { "utc": "2026-09-10T03:05:00.000Z" }
  },
  "checks": [
    { "id": "api_node", "status": "ok", "detail": "API node service is up.", "hint": null },
    { "id": "db", "status": "ok", "detail": "Database service is up.", "hint": null },
    {
      "id": "clock_skew",
      "status": "ok",
      "detail": "Node clock is 1,000 ms behind this machine's clock (warn at 15,000 ms, fail at 30,000 ms).",
      "hint": null
    },
    {
      "id": "chain_tip_age",
      "status": "ok",
      "detail": "Latest block (height 5,763,675) is 201 s old (about 3.4 min; warn above 300 s, fail above 900 s).",
      "hint": null
    }
    // … and storage_consistent, finalization_lag and roles
  ]
  // … then node, network, chain, storage, peers, time and notes
}

verdict は 7 つのチェックを 1 つの単語にまとめ、sync.synced はノードがチェーンに追従しているかどうかを示します（判断できない場合は null）。ok ではないチェックには次の手順を示す hint が付き、summary ではそれぞれが独立した行に表示されます。リクエストが失敗すると、そのチェックは unknown になり、フィールドは null になりますが、呼び出しは引き続き回答を返します。

「ハーベスティングで月ごとにいくら稼ぎましたか？」 → symbol_harvesting_income { "account": "NCV5HR…", "fromDate": "2026-09-01", "toDate": "2026-09-11", "granularity": "monthly" }

NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY on mainnet, 2026-09-01 to 2026-09-11 (Asia/Tokyo; heights 5,736,305-5,767,984, 31,680 blocks): 20 harvest receipts totalling 662.574177 symbol.xym from 11 blocks (harvester share 461.240390 in 9 receipts, beneficiary share 201.333787 in 11 receipts).
Blocks: 9 harvested by this account, 2 harvested by others that paid it only the beneficiary share (typically delegators on its node). 9 of the 11 beneficiary receipts come from blocks it harvested itself, as its own node's beneficiary.
2026-09: 20 receipts, 662.574177 symbol.xym; 11 blocks: 9 harvested by this account, 2 by others (receipts 9 harvester / 11 beneficiary)

これは summary です。同じ数値が totals と monthly[] にも含まれ、それぞれの金額は小数文字列（"662.574177"）と生の整数値（"662574177"）の両方で、サーバーによって合計されています。報酬レシートはブロック報酬の分配分です。そのため、自身が運用するノードの受益者でもある運用者は、ハーベストしたブロックごとに 2 件のレシートを受け取ります。blocksHarvested と blocksBeneficiaryOnly はブロック数を数えます。

要件

• Node.js 22 以降。
• https:// 経由でアクセス可能な Symbol REST ノード（一般的なパブリックノードではポート 3001）。パブリックノードの一覧は https://nodewatch.symbol.tools/ にあります。

インストール

Claude Desktop：ワンクリックバンドル（.mcpb）

1. Releasesから最新のsymbol-mcp-server-<version>.mcpbをダウンロードします。
2. ダブルクリックするか、Claude DesktopのSettings → Extensionsを開いて、そこからインストールします。
3. 設定フォームにSymbol node URLを入力します。例：https://<node-host>:3001（独自のノードが最適です。ノードの選択を参照してください）。必須項目です。入力しないと拡張機能は起動しません。必要に応じてタイムゾーンと状態ディレクトリも設定します。このディレクトリにはs​​ymbol_harvesting_statusがスナップショットを保存します。それ以外のフィールドは空のままで構いません。
4. 拡張機能を有効にします。

これらの設定を後で変更した場合は、新しい会話で試してください。

このバンドルには、公開されたnpmパッケージからビルドされたサーバーと本番環境用の依存関係が含まれており、Claude Desktopに付属するNode.jsで実行されます。バンドルと以下のnpx設定のどちらか一方を使用してください。両方を使うと、各ツールが二重に表示されます。バンドルはmcpb signで署名されていないため、Claude Desktopで拡張機能が未検証と表示される場合があります。リリースワークフローで添付されるビルド来歴を使って、配布元を確認できます。

gh attestation verify symbol-mcp-server-<version>.mcpb --repo inotakeh/symbol-mcp-server

npmとソース

npmから（その他すべてのMCPホストでの使用を推奨）：

npx -y symbol-mcp-server --help

MCP Registryにもio.github.inotakeh/symbolとして登録されています。

ソースから：

git clone https://github.com/inotakeh/symbol-mcp-server.git
cd symbol-mcp-server
npm ci
npm run build
SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js

node dist/index.js --helpは環境変数を標準エラー出力に表示して終了し、--versionはバージョンを表示します。この2つとcheckサブコマンド（CLI：cronによる監視を参照）を除き、バイナリは引数を受け取りません。すべて環境変数で設定するため、モデルが別のホストを指定することはできません。

MCPホストを設定する

このサーバーはstdio経由でMCPを使用します。起動時に/node/infoを取得し、ジェネレーションハッシュシードからメインネットかテストネットかを判別して、標準エラー出力に1行記録します。

symbol-mcp-server <version>: mainnet via <node-host>:3001, timezone Asia/Tokyo

Claude Desktop

claude_desktop_config.jsonに追加します。npmパッケージを使用する場合：

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": {
        "SYMBOL_NODE_URL": "https://<node-host>:3001",
        "SYMBOL_TIMEZONE": "Asia/Tokyo"
      }
    }
  }
}

ソースのチェックアウトから使用する場合：

{
  "mcpServers": {
    "symbol": {
      "command": "node",
      "args": ["/path/to/symbol-mcp-server/dist/index.js"],
      "env": {
        "SYMBOL_NODE_URL": "https://<node-host>:3001"
      }
    }
  }
}

Claude Code

claude mcp add symbol -s user -e SYMBOL_NODE_URL=https://<node-host>:3001 -e SYMBOL_TIMEZONE=Asia/Tokyo -- npx -y symbol-mcp-server
# or, from a source checkout:
claude mcp add symbol -s user -e SYMBOL_NODE_URL=https://<node-host>:3001 -- node /path/to/symbol-mcp-server/dist/index.js

または、プロジェクトレベルの.mcp.jsonをコミットします：

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

その他のクライアント

同じnpxコマンドは、stdioサーバーを起動するすべてのMCPホストで使用できます。以下のファイルの場所と形式は、各クライアントのドキュメントに基づいています。

**Cursor：**すべてのプロジェクトで使用する場合は~/.cursor/mcp.json、1つのプロジェクトで使用する場合はプロジェクト内の.cursor/mcp.jsonです。

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

VS Code：ワークスペース内の.vscode/mcp.json、またはMCP: Open User Configurationコマンドで開くユーザーレベルのファイルです。トップレベルのキーはmcpServersではなくserversです。

{
  "servers": {
    "symbol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

Cline：ClineパネルでMCP Servers → Configure → Configure MCP Serversを開き、mcpServersの下にサーバーを追加します（Cline CLIは~/.cline/mcp.jsonから同じ形式を読み込みます）。

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windowsでは、npxを起動できないクライアントに"command": "npx.cmd"が必要な場合があります。

環境変数

変数	必須	意味
SYMBOL_NODE_URL	はい	クエリ対象ノードのREST URL。例：https://<node-host>:3001。https://が必須です（localhost／127.0.0.1／[::1]の場合のみhttp://を使用できます）。ポートは指定された値をそのまま使用します。
SYMBOL_NETWORK	いいえ	mainnetまたはtestnetです。設定すると、ノードが異なるネットワークを報告した場合、起動に失敗します。
SYMBOL_TIMEZONE	いいえ	Asia/TokyoなどのIANAタイムゾーンです。各UTCタイムスタンプの横に現地時刻を追加します。
SYMBOL_REFERENCE_NODES	いいえ	symbol_network_compareとsymbol_version_driftが照合する、カンマ区切りのhttps://ノードURLです。ほかのホストにアクセスすることはありません。
SYMBOL_REQUEST_TIMEOUT_MS	いいえ	リクエストごとのタイムアウト。100～600000です。デフォルトは10000です。
SYMBOL_STATE_DIR	いいえ	symbol_harvesting_statusが、ノードごとに1つのスナップショットファイル（ロックされていないハーベスタの公開鍵、高さ、時刻。秘密情報は含みません）を保存する際に使用する絶対パスのディレクトリです。初回の保存時にモード0700で作成されます。未設定の場合、このツールは比較を行わずに現在の一覧を報告します。

ノードを選ぶ

• ご自身のノードが最適です。 SYMBOL_NODE_URL には、検索した内容（アドレス、トランザクションハッシュ、ネームスペースとモザイクの ID）が送信されます（全項目についてはプライバシーポリシーをご覧ください）。参照ノードに送信されるのは /node/info と /chain/info のリクエストのみで、識別子が送信されることはありません。
• パブリックノードも利用できますが、運営者には検索した内容が見えます。 アクセスログから、どのアカウント、トランザクション、ネームスペースが、いつ、どの IP アドレスから照会されたかが分かる場合があります。信頼できるノードを使うか、プライベートにしておきたい情報を扱う場合はご自身のノードを使ってください。
• API ノードの REST API が必要です。 ほとんどのツールは /network/properties、アカウント、トランザクション、ブロックを読み取ります。エンドポイントが制限された REST である Light REST では不十分です。Symbol リポジトリ（symbol/symbol の client/rest/README_LIGHT.md）にある README に記載されているのは、/chain/info、/node/info、/node/peers、/node/unlockedaccount、/node/server のみです。ツールが does not provide the endpoint … (no such route) と応答する場合は、トラブルシューティングをご覧ください。
• ノードを探すには： https://nodewatch.symbol.tools/ で、メインネットとテストネットのノード、そのブロック高とバージョンを確認できます。現在のブロック高に達していて、最も多く使われているバージョンを実行し、https:// で応答する API ノード（通常はポート 3001）を選んでください。ノードが別のネットワークに接続されていた場合に起動時に失敗するよう、SYMBOL_NETWORK を設定してください。次のコマンドで動作を確認できます。 SYMBOL_NODE_URL=https://<node-host>:3001 npx -y symbol-mcp-server check

ツール

20 個のツールはすべて読み取り専用（readOnlyHint: true）で、固定された順序で一覧表示されます。引数に指定するのは識別子のみで、URL は指定しません。すべての account 引数（および symbol_transaction_search の address）には、base32 アドレス、48 文字の 16 進アドレス、16 進形式の公開鍵、または alice や alice.pay のようにアドレスエイリアスを持つネームスペース名を指定できます。名前の解決結果は accountResolution とサマリーの冒頭に表示されます。

ツール	引数	回答
symbol_network_info	なし	ネットワーク名／識別子とジェネレーションハッシュシード、現在および確定済みの高さ、ファイナライゼーションエポック、ブロック目標時間、投票セットのグループ化、エポック調整、XYM モザイク ID／エイリアス／可分性、現在の手数料乗数。
symbol_node_status	format	設定済みのノードは同期しているか、サービスは現在正常か、そしてどのような状態かを返します。固定順序の 7 つのチェックから、healthy、degraded（警告がある、または確認できなかった項目がある）、unhealthy のいずれか 1 つの判定を返します。各チェックの状態は ok／warn／fail／unknown で、ヒントも含まれます。チェック項目は、API ノードとデータベースの状態（503 の /node/health 応答は読み取りますが、失敗とはみなしません）、データベースのブロック数とチェーンの高さの比較、このマシンの時計に対するノードの時計、ブロック数と分数で示すファイナライゼーションの遅延、ロール、最新ブロックの経過時間とこのマシンの時計との比較です。最後の項目は、チェーンへの追従を停止したノードを検知します（目標ブロック時間の 10 倍を超えると警告、30 倍を超えると失敗）。sync.synced は、最新ブロックの経過時間が目標ブロック時間の 10 倍以内（メインネットでは 5 分）なら true、それを超えると false、判定できない場合は null です。フレンドリー名、ホスト、ロール（Peer／API／Voting）、デコード済みバージョン、ネットワーク、高さ、ピア数、データベースの各種件数、ノードの時計も含まれます。リクエストに失敗した場合、そのチェックは unknown となり、該当フィールドは null になりますが、呼び出し自体は失敗しません。しきい値はネットワークプロパティから導出されます。
symbol_account_get	account（アドレス、公開鍵、またはネームスペース名）、format	base32 と 16 進数形式のアドレス、公開鍵、エイリアスと小数桁数を含むすべてのモザイク残高、インポータンス、リンク済み／VRF／ノード／投票鍵、委任ハーベスティングが設定済みかどうか、マルチシグ設定（マルチシグアカウントとして、または連署者として）。
symbol_voting_key_status	account	すべての投票鍵とその状態（期限切れ／有効／将来有効）、残りのエポック数／ブロック数／日数、推定有効期限、推奨更新期間（7 日前から 3 日前まで）、期限切れの鍵も含むスロット使用状況、minVoterBalance に照らした投票者の適格性、警告。
symbol_transaction_get	transactionHash	確定済み、未確定、部分署名済みのグループを検索し、状態を報告します。トランザクションの種類名、署名者と受取人、エイリアス付きモザイク、デコード済みのプレーンメッセージまたは「暗号化済み」のマーカー、手数料、高さと時刻、アグリゲートの内部トランザクションを返します。ノードが拒否したトランザクションは失敗として報告され、ノードのコードとその意味も示されます。ノードが認識していないハッシュは not_found として報告されます。
symbol_transaction_search	address、type、pageSize、pageNumber、order、format	アカウントが関与する確定済みトランザクションを返します。デフォルトでは新しい順で、種類名（transfer）またはコード（16724）による任意のフィルターを指定できます。1 ページあたり 10～100 件です。
symbol_mosaic_get	mosaic（16 進数 ID または symbol.xym などのエイリアス）	供給量、可分性、フラグ（供給量変更可能、譲渡可能、制限可能、失効可能）、所有者、開始高さ、期間、推定有効期限。
symbol_namespace_get	namespace（名前または 16 進数 ID）	所有者、ルートまたはサブネームスペース、各階層の名前、エイリアスの対象（アドレスまたはモザイク）、開始および終了高さ、推定有効期限。
symbol_fee_estimate	transactionSizeBytes（任意）	ノードの現在の乗数から計算した、遅い／平均／中央値／速い手数料の段階を XYM で返します。指定されたサイズを使うか、指定がない場合はモザイク 1 個と 20 文字の ASCII メッセージを含む転送トランザクション（197 バイト）を使います。転送は 160 バイト、モザイクごとに 16 バイト、プレーンメッセージは UTF-8 バイト数にタイプバイト 1 バイトを加えて計算します（日本語 1 文字あたり通常 3 バイト。暗号化メッセージはさらに大きくなります）。このサイズ計算はアグリゲートトランザクションには適用されません。署名も送信も行いません。
symbol_address_parse	value（アドレス、公開鍵、またはネームスペース名）	オフラインで検証します。チェックサム、ネットワークバイト、base32／16 進数／ハイフン区切り形式、公開鍵から導出されるアドレスを確認します。ネームスペース名はノードを通じて解決し、アドレスのエイリアスを取得します。
symbol_time_convert	height、epoch、timestamp のいずれか	高さ、ファイナライゼーションエポック、ネットワークタイムスタンプ、実時間を返します。過去の時刻は正確で、未来の時刻は推定値（その旨を示すフラグ付き）です。
symbol_harvesting_status	mode（current、compare、compare_and_save、save_only）、format	ノードでロック解除されている委任ハーベスターについて、現在の数、ハーベスティング制限、受益者の割合を返します。current（デフォルト）はノードのみを読み取り、鍵自体は format: detailed で取得できます。その他のモードでは、前回保存されたスナップショット以降にハーベスターが増減したかどうかを返します。追加および削除されたリモート鍵、件数の差、過去 30 日間のスナップショットにおける最小値／最大値／平均値が含まれます。スナップショットは SYMBOL_STATE_DIR の下にノードごとに 1 ファイル保存されます。この変数がない場合は現在のリストを返しますが、比較はできません。compare は読み取りのみ、compare_and_save は現在のリストも保存、save_only は比較せずに保存します。特定のアカウントについて（リンク済み鍵がここでロック解除されているか、残高が制限内か）確認するには、symbol_delegation_diagnose を使用してください。
symbol_network_compare	なし	ノードの高さとファイナライゼーションを SYMBOL_REFERENCE_NODES と比較し、最良のノードからのブロック数の遅れと lagging フラグを返します。参照ノードが設定されていない場合にどうすればよいかを説明し、比較できた参照ノードがない場合はその旨を示します。
symbol_harvesting_income	account、fromDate + toDate または fromHeight + toHeight、granularity、format、output	期間中に受け取ったハーベスティング報酬を返します。レシート数と正確な XYM 合計（サーバー上で整数として合算）、ハーベスター／受益者／不明の内訳、ブロック数（blocksHarvested：アカウントがハーベストしたブロック、blocksBeneficiaryOnly：他のアカウントがハーベストし、受益者分のみを支払ったブロック）、SYMBOL_TIMEZONE または UTC における日ごとの集計、またはレシートの一覧が含まれます。日付はブロックのタイムスタンプから高さに変換されます。granularity: monthly を指定すると、暦月ごとに 1 行を返します（年単位の質問向け）。output: csv を指定すると、JSON も引き続き利用できる状態で、スプレッドシート用に行を CSV テキストとして返します。1 年以上の期間を 1 回の呼び出しで指定できます。範囲は約 90 日ごとのチャンクで読み取られます（fetch にチャンク、再試行、ページ数が表示されます）。
symbol_transaction_status	transactionHashes（配列、1～20 件）	各トランザクションの現在の状態を返します。確定済み（高さ付き）、未確定、部分署名済み（連署を待機中）、失敗（ノードのコードとその意味付き）、または not_found のいずれかです。バッチ全体を 1 回のリクエストで確認します。
symbol_finality_participation	account、epoch（任意、デフォルトは最新の確定済みエポック）、epochs（1～20、デフォルトは 1）、format	アカウントの投票鍵が各エポックのファイナライゼーション証明に実際に署名したかどうかを返します。状態は、参加（prevote と precommit の両方）、未参加（署名されなかった段階を表示）、有効な鍵なし、または利用不可です。段階ごとの署名数も含まれます（証明で複数のメッセージグループに分割される段階は 1 段階として数え、いずれかのグループに署名があればカウントします）。現在のエポックをカバーする鍵がない場合、または現在のエポックで投票を逃した場合は警告します（過去のエポックでは警告しません）。
symbol_delegation_diagnose	account、recentDays（1～30、デフォルトは 7）、format	委任ハーベスティングが有効かどうか、有効でない場合はどこで止まっているかを確認します。アカウントの存在、残高がハーベスティング制限内か、インポータンスがゼロより大きいか（または次回の再計算までのブロック数）、リンク済み／VRF／ノード鍵、ノード鍵が設定済みノードの nodePublicKey と一致するか、リモート鍵がそのノードでロック解除されているか、アカウント種別、過去 N 日間にハーベストしたブロック数、ノードへの永続的な委任リクエスト転送を確認します。判定は active、not_active、または cannot_verify（他のノードへの委任はここから確認できません）です。
symbol_version_drift	format	ノードのソフトウェアバージョンがネットワークの多数派より古いかどうかを確認します。ノードが把握しているピアと参照ノードのバージョンを、最多バージョンと、より新しいものを実行している割合を含む分布として返します。判定は ok、behind（多数派より古い、または新しいバージョンがサンプルの半数以上を占める）、far_behind（75％以上がより新しいバージョン。ピアが接続を拒否する可能性があります）、または unknown（利用可能なピアがいない、またはノード自身のバージョンが報告されていない）です。まだバージョンを報告していないピア（0.0.0.0）はバージョンとして扱わず、別にカウントします（sample.unknownVersion）。ピアのホストと鍵は報告されません。
symbol_account_rank	account（任意）、mosaic（任意。16 進数 ID またはエイリアス、デフォルトは XYM）、top（1～100、デフォルトは 20）、maxRank（100～5000、デフォルトは 1000）、format	モザイク保有者の中でのアカウントの順位と、上位保有者をエクスプローラーのリッチリストのように返します。アカウントの残高、供給量に占める割合（小数点以下 4 桁、整数演算）、順位、残高と割合を含む上位 N 人の保有者、上位 N 人の合計割合が含まれます。アカウントが見つかるか maxRank に達するまで、GET /accounts?orderBy=balance を 1 リクエストあたり 100 件で、同時に 1 件ずつ読み取ります（その場合は rankBeyond がその旨を示します）。上位リストのみを取得する場合は account を省略してください。同順位の順序はノードに従い、取引所や財団などのラベルは付与されません。
symbol_holdings_value	account、unitPrice（10 進数の文字列、例："12.34"）、currency（大文字の英字 3～6 文字）、priceSource（任意）、priceAsOf（任意）、mosaic（任意、デフォルトは XYM）、decimals（任意、0～12）、format	呼び出し元が指定した単価で、アカウントのモザイク残高がいくらになるかを返します。残高、正規化した価格、正確な積、四捨五入した積を、すべて整数演算で返します。丸めでは、Intl（Unicode CLDR）が通貨に対して定める桁数を使います（JPY は 0 桁、USD は 2 桁、KWD は 3 桁、CLF は 4 桁）。CLDR の桁数は一部のコードで ISO 4217 と異なります（HUF、IDR、IQD、IRR は CLDR では 0 桁ですが、ISO 4217 では IQD が 3 桁、その他は 2 桁です）。また、桁数はサーバーを実行する Node.js によって決まるため、固定するには decimals を指定してください。Intl が認識しないコード（BTC、USDT）は丸められません。また、ゼロ以外の値が丸めによって 0 になる場合も丸めません。どの規則が適用されたかは value.decimalsSource で示されます。サーバーは価格を取得も検証もしません。回答に価格の出所を示すため、priceSource と priceAsOf はそのまま返されます。税計算ではないため、手数料、スプレッド、税金は含まれません。

質問の例

「NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY の投票キーはいつ期限切れになりますか。また、いつ更新すればよいですか？」 → symbol_voting_key_status { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY" } 各キーの startEpoch／endEpoch、有効期限の高さ (endEpoch - 1) × votingSetGrouping、残りエポック数・ブロック数・日数、実測した平均ブロック時間に基づく有効期限の推定日、更新期間、空きスロット（期限切れのキーもスロットを占有します）、残高が minVoterBalance を満たしているかを返します。

「alice のアカウントを表示してください。」 → symbol_account_get { "account": "alice" } 名前空間 alice はノードを介してアドレスエイリアスに解決されます（見つからない名前空間、期限切れの名前空間、モザイクエイリアスの名前空間、またはエイリアスのない名前空間は、ヒント付きのエラーになります）。回答は alice → NCV5… から始まり、解決結果を accountResolution に含みます。すべてのアカウント引数で利用できます。

「NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY は XYM をいくら保有していますか？」 → symbol_account_get { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY" } alias（symbol.xym）、amount（小数点以下の桁数を適用した値）、rawAmount を含む、すべてのモザイクを返します。

「このアカウントが関係する最新の送金を20件表示し、そのうち最も新しい取引の詳細を表示してください。」 → symbol_transaction_search { "address": "NCV5HR…", "type": "transfer", "pageSize": 20 } → symbol_transaction_get { "transactionHash": "<hash from the list>" } 一覧にはハッシュ、日付、取引相手、メッセージのプレビューが表示されます。2回目の呼び出しでは、手数料、デコードされた完全なメッセージ、内部トランザクションが追加されます。

「自分のノードは遅れていますか？」 → symbol_node_status {} は、設定されたノードの最新ブロックの経過時間を確認します。 → symbol_network_compare {} は、SYMBOL_REFERENCE_NODES より何ブロック遅れているかを報告します。

「NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY は2026年8月のハーベスティングでいくら獲得しましたか？」 → symbol_harvesting_income { "account": "NCV5HR…", "fromDate": "2026-08-01", "toDate": "2026-08-31" } 日付をブロック高に変換し、アカウント宛てのすべての HarvestFee レシートを読み取り、正確な整数として合計します。合計 XYM、ハーベスターとベネフィシャリーの取り分、日ごとの内訳を返します。モデル側で合計する必要はありません。

「投票キーのリンクを通知したところです。トランザクション <hash> は処理されましたか？」 → symbol_transaction_status { "transactionHashes": ["<hash>"] } confirmed（高さを含む）、unconfirmed、partial（署名待ちのアグリゲートボンデッド）、failed（Failure_Core_Insufficient_Balance のようなノードのコードとその意味を含む）、または not_found のいずれかを返します。常に配列で返し、1回の呼び出しにつき最大20個のハッシュを指定できます。

「自分の投票ノード NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY は、実際に先週投票できましたか？」 → symbol_finality_participation { "account": "NCV5HR…", "epochs": 14 } 最新の確定済みエポックのファイナライゼーション証明と、その前の13エポックを読み取ります（1エポックは votingSetGrouping ブロックで、メインネットでは約12時間です）。各エポックについて、アカウントの投票キーのいずれかが両ステージの署名者に含まれているか、何人の投票者が署名したかを報告します。また、現在のエポックを逃した場合、またはそれをカバーするキーがない場合は警告します。

「デリゲートハーベスティングが機能していないようです。NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY を確認してください。」 → symbol_delegation_diagnose { "account": "NCV5HR…" } 11項目のチェックを決められた順序で実行します（存在、残高制限、インポータンス、3つのキーリンク、ノードキーと設定済みノードの照合、そのノードでロック解除されているか、アカウントタイプ、最近ハーベストされたブロック、委任リクエストのトランザクション）。結果として active、not_active（失敗したステップとヒントを含む）、または cannot_verify（アカウントが SYMBOL_NODE_URL とは別のノードに委任しているため、ノード側を確認できない）を返します。 「ノードは正常ですか？ バージョンは遅れていますか？」 → symbol_node_status {} は、設定済みノードの API ノード、データベース、ストレージ、クロック、ファイナライズの遅延、最新ブロックの経過時間を確認し、失敗したチェック項目とともに正常／低下／異常を回答して、ノードが同期済みかどうかを示します； → symbol_version_drift {} は、ノードのバージョンをピアおよび参照ノードと比較し、問題なし／遅れ／大幅な遅れを回答します。どちらも、ノードの OS 移行後に最初に確認すべき項目です。

「移行後、委任者は戻ってきましたか？」 → symbol_harvesting_status { "mode": "compare_and_save" } は、現在ノードでロック解除されているハーベスターを最後に保存したスナップショットと比較し（追加・削除されたキー、件数の差、30 日間の最小値／最大値／平均値）、今日のリストを次回のチェック用に保存します；保存せずに確認するには "mode": "compare" を使います。SYMBOL_STATE_DIR が必要です。指定されていない場合、ツールは現在の件数を報告し、比較できないことを伝えます。モードを指定しない場合、ツールは「現在の委任者数は？」に回答し、スナップショットには触れません。

「NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY の XYM 保有量順位は？ 上位 10 アカウントは？」 → symbol_account_rank { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY", "top": 10 } 残高順の保有者リストを一度に 100 アカウントずつ読み込み、対象アカウントが見つかるか、maxRank（デフォルトは 1000）に達するまで続けます。対象アカウントの残高、供給量に占める割合、順位を、上位 10 保有者とその合計割合とともに返します。割合はすべてサーバー上で整数演算により計算されます。リストの上位は通常、取引所や財団のアカウントですが、ツールはアカウント名を付けません。

「XYM が 12.34 円の場合、保有分はいくらですか？ NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY」 → symbol_holdings_value { "account": "NCV5HR…", "unitPrice": "12.34", "currency": "JPY" } 残高を読み取り、価格を整数演算で乗算します。4,321,000 XYM の場合は 53,321,140 JPY となり、正確な積も併せて返します。価格は呼び出し元から渡されます。 このサーバーは価格 API に接続しません（SYMBOL_NODE_URL とのみ通信します）。そのため、「今、保有分はいくらですか？」と尋ねる場合、Claude Desktop では、モデルが先に価格を調べ（ウェブ検索、価格を提供する別の MCP サーバーを利用、またはユーザーが入力）、その後 unitPrice、currency、できれば priceSource／priceAsOf も指定してこのツールを呼び出す流れになります。これにより、価格がいつどこで確認されたかも回答に示されます。モデルには、残高と価格の乗算を自分で行わないよう指示されています。

各ケースで想定される正確な引数を含むその他の例は、evals/cases.json にあります。

プロンプト

2つの MCP プロンプト（prompts/list）には、ノード運用者が繰り返し行うツール呼び出しがまとめられています。どちらも1つの引数accountを受け取ります。これは投票／ハーベスティングアカウントの39文字の base32 アドレスです。 プロンプトのテキスト自体には、アドレス、ホスト、キー、日付は含まれていません。

プロンプト	手順の内容
voting_key_renewal_checklist	symbol_voting_key_status（有効期限、更新期間、空きスロット、および表示された警告）、symbol_node_status（同期されていない場合、または同期状況を判定できない場合は中止。判定結果と問題のあるチェック項目は未解決項目に記載）、symbol_network_compare（比較できなかった場合は同期を未確認として報告）、その後、運用者がこのサーバー外で VotingKeyLink を通知した後に、ハッシュを指定してsymbol_transaction_statusを実行し、新しいキーを確認するために2回目のsymbol_voting_key_statusを実行し、新しいキーの開始エポックがファイナライズされた時点でsymbol_finality_participationを実行します。最後に4行の要約を出力します。
monthly_health_check	symbol_node_status（判定結果、同期状況、バージョン、ピア数。不健全な状態を最初に報告）、symbol_version_drift（behindまたはfar_behindの場合は最初に報告）、symbol_network_compare（比較できなかった場合は同期を未確認として報告）、symbol_harvesting_statusをモードcompare_and_saveで実行（前回のスナップショットとの差分）、symbol_voting_key_status（残り日数と有効期限。表示された警告を最初に報告）、symbol_account_get（残高とminVoterBalanceの比較）、および前暦月のsymbol_harvesting_income（収入、そのアカウント自身がハーベストしたブロック、委任者などがハーベストしたブロックを個別の項目として報告）。「対応が必要」「注意」「正常」のいずれかに分類して1画面に報告します。

サーバーは、初期化時に短いinstructionsも送信します（読み取り専用、アカウント形式、混同しやすい質問にどのツールが答えるか：ハーベスティング収入、投票キー、ノードの状態と同期状況とバージョンの違い、トランザクションが処理されたかどうか。返された数値はそのまま使用します）。関連する質問に答えるツールは、説明の中で互いを案内しています。

CLI：cron による監視

同じバイナリには MCP クライアントを必要としない、1回限りのcheckサブコマンドがあります。上記のツールでノードを判定し、レポートを1つ出力して、問題がある場合はゼロ以外の終了コードで終了します。

symbol-mcp-server check [--account <address|publicKey|namespace>] [--warn-days <n>]
                        [--cert <path>]... [--cert-warn-days <n>]
                        [--format text|json] [--quiet]

サーバーと同じ環境変数を読み込みます（SYMBOL_NODE_URLは必須、SYMBOL_TIMEZONE、SYMBOL_REFERENCE_NODES、SYMBOL_STATE_DIRは任意）。また、Node.js 22以降が必要です。引数なしで起動した場合、バイナリはこれまでどおり MCP サーバーとして動作します。

#	項目	ok / warn / fail
1	node_health	symbol_node_status の判定結果です：healthy / degraded / unhealthy。最新ブロックが目標ブロック時間の10倍（メインネットでは5分）より古いノードは degraded、30倍より古い場合は unhealthy です
2	version_drift	symbol_version_drift：ok / behind または unknown / far_behind
3	harvester_watch	モード compare_and_save の symbol_harvesting_status です：前回の実行時よりロック解除済みハーベスターが少ない場合、またはスナップショットを保存できなかった場合は warn です。SYMBOL_STATE_DIR が設定されていない場合はスキップされます
4	voting_key_status	--account を指定した場合：有効な投票キーの有効期限が --warn-days（デフォルトは14、1～120）の範囲内に迫っている場合は warn、3日以内の場合、または有効なキーがない場合は fail です。後継キーがすでに登録されていて、空白期間がない場合は ok です。後継キーの有無にかかわらず、残高が minVoterBalance 未満（アカウントが投票できない状態）の場合も fail です。キーのスロットがすべて埋まっていてもステータスは変わりませんが、その場合に warn または fail となると、後継キーがすでに登録されていない限り、ヒントにツールのスロット警告が追加されます。--account が指定されていない場合はスキップされます
5	finality_participation	--account を指定した場合、最新のファイナライズ済みエポックについて、参加済み／ノード上に証明がない、または参加なし／そのエポックをカバーするキーなしを示します。--account が指定されていない場合はスキップされます
6	certificate	--cert <path> を指定した場合、ノード証明書の各コピーを個別に判定します：証明書の有効期限が切れている場合、または残り有効期間が7日未満の場合は fail、--cert-warn-days（デフォルトは30）未満の場合、またはファイルが同じ証明書のコピーではない場合は warn です。ファイルを読み取れない場合、または証明書ではない場合は、理由とともに fail になります。--cert が指定されていない場合はスキップされます。ノード証明書ファイルを参照してください

項目1～5の判定は各ツール独自のもので、このチェックはその出力を読み取るだけです。warn または fail の行の下に表示されるヒントは、ツールが返したテキストです。ツールが失敗した場合（たとえば、HTTP エラー）、その項目は fail となりますが、ほかの項目のチェックは続行されます。例外は項目6です。ノードの証明書ファイルを表示する REST エンドポイントはないため、このチェックはファイルを直接読み取り、背後で呼び出す MCP ツールはありません。

終了コード	意味
0	すべての項目が ok またはスキップ
1	1つ以上の警告があり、失敗はない
2	1つ以上の失敗がある
3	チェックを実行できませんでした：設定エラー、ノードに到達できない、または引数が不正（理由は stderr に1～2行で表示されます）。--cert を指定していて、ノードを読み取れなかった場合も証明書ファイルは判定され、結果が報告されます。ノード証明書ファイルを参照してください

テキスト出力（デフォルト。値は説明用です）：

symbol check: WARN (node.example:3001, mainnet, 2026-01-15T07:00:03+09:00)
[ok] node_health: healthy (finalization lag 12 blocks)
[ok] version_drift: ok. node.example:3001 runs 1.0.3.9; majority of 24 sampled nodes runs 1.0.3.9; 0% run something newer.
[ok] harvester_watch: 18 unlocked harvesters on node.example:3001, unchanged since 2026-01-14T07:00:02+09:00 (2026-01-13T22:00:02.000Z). Snapshot saved (31 stored).
[warn] voting_key_status: active key 0A1B2C3D… expires in about 12.4 days (epoch 4321, estimated 2026-01-27T16:40:00+09:00 (2026-01-27T07:40:00.000Z))
  hint: Active voting key 0A1B2C3D… expires at epoch 4321 in about 12.4 days (...) and no successor key is registered.
[ok] finality_participation: epoch 4290: participated (signed prevote and precommit)
[skip] certificate: no --cert given; pass --cert <path> for each copy of the node certificate to check its expiry

--format json は、同じレポートを1つの JSON ドキュメントとして出力します：{ verdict, exitCode, node: { host, network }, checkedAt, checks: [{ id, status, detail, hint }], warnDays, account }。verdict は ok、warn、fail、error（終了コード3）のいずれかで、account は解決済みアドレスです。起動時に /node/info を読み取れず、--cert が指定されていた場合、network は unknown、ノードに問い合わせる5項目は skip、certificate は ok、warn、または fail となり、account は指定された引数のままです（16文字を超える場合は先頭8文字と … に短縮されます）。全体の結果は項目ではなく、verdict（error）と exitCode（3）で確認してください。--quiet は終了コードが0の場合に何も出力しないため、cron は確認すべき内容がある場合にのみメールを送信します：

[email protected]
0 7 * * * SYMBOL_NODE_URL=https://node.example:3001 SYMBOL_STATE_DIR=/var/lib/symbol-mcp-server \
  npx --yes symbol-mcp-server check --account NXXX... --warn-days 14 --quiet \
  --cert /path/to/target/nodes/node/cert/node.crt.pem \
  --cert /path/to/target/gateways/rest-gateway/api-node-config/cert/node.crt.pem

ここではページに収めるためエントリを複数行に分けています。cron には行の継続機能がないため、crontab には1行で記述してください。

• このチェックは通知を送信しません。 stdout と stderr に出力し、終了コードを設定します。メール送信は cron の役割です（MAILTO）。接続するのは SYMBOL_NODE_URL と SYMBOL_REFERENCE_NODES のみで、それ以外には接続せず、サーバーと同様に読み取り専用です。SYMBOL_STATE_DIR が設定されている場合、実行のたびに symbol_harvesting_status が使用するファイルにスナップショットを 1 つ追記します（最新の 60 件が保持されます）。--cert を指定すると、実行中のマシン上にある指定されたファイルを読み取ります。それらのファイルの内容が外部に送信されることはありません。
• 実行全体は 120 秒に制限されます。制限時間に達すると、残りの項目はスキップされ、その理由が stderr に出力され、結果は最大でも WARN となり、--quiet を指定していても出力されます。起動時に /node/info を読み取れない場合は、この制限は適用されません（ノード証明書ファイルを参照）。この場合、それ以上のリクエストは行われず、--cert のファイルは各最大 1 MiB まで読み取られるだけです。
• サブコマンド名に誤字がある場合は、サーバーの不明な引数として扱われ、従来どおり 2 で終了します。

ノードの証明書ファイル（--cert）

symbol-bootstrap でセットアップしたノードの証明書は、2 か所にあります。ノード自体は target/nodes/node/cert/node.crt.pem を使用し、REST ゲートウェイには target/gateways/rest-gateway/api-node-config/cert/node.crt.pem に独自のコピーがあります。symbol-bootstrap renewCertificates は前者を更新しますが、後者には触れません。REST ゲートウェイのコピーだけが期限切れになると、ゲートウェイはノードと通信できなくなり、/node/health は apiNode: down を報告します。両方のファイルを渡せば、check がその前に知らせてくれます。

symbol-mcp-server check --cert target/nodes/node/cert/node.crt.pem \
  --cert target/gateways/rest-gateway/api-node-config/cert/node.crt.pem

[warn] certificate: warn (copies differ: target/nodes/node/cert/node.crt.pem vs target/gateways/rest-gateway/api-node-config/cert/node.crt.pem)
  target/nodes/node/cert/node.crt.pem: ok, expires 2027-01-20T02:11:09.000Z, 370 days left, sha256 0A:1B:2C:…
  target/gateways/rest-gateway/api-node-config/cert/node.crt.pem: ok, expires 2026-03-01T02:11:09.000Z, 45 days left, sha256 3D:4E:5F:…

• 各ファイル：証明書の有効期限が切れているか、残り日数が 7 日未満の場合は fail（固定値で、オプションではありません）。--cert-warn-days 日未満の場合は warn（デフォルトは 30。1 以上の整数で、--warn-days とは独立しています）。それ以外は ok です。残り日数は現在から証明書の notAfter までの日数を整数に切り捨てた値で、最終日は 0 として数えます。複数の証明書を含むファイル（node.full.crt.pem）は、最初の証明書で判定されます。
• コピー：ファイルが 2 つ以上ある場合、SHA-256 フィンガープリントがすべて同じでなければなりません。同じでない場合、項目は少なくとも warn となり、異なるファイルの名前が示されます。一方のコピーだけが更新された場合、古いコピーの期限が切れるずっと前に、同じ日にこれが表示されます。同じパスを 2 回指定することは、ファイル自身と比較することになるため、使用方法のエラーとして拒否されます（パスは記述どおりに比較され、. と .. を解決した後の値を使います。同じファイルへのリンクや、大文字と小文字を区別しないファイルシステム上での別表記は検出されません）。
• 項目の判定結果は、各ファイルと比較結果のうち最も悪いものです。ファイルを読み取れない場合や証明書でない場合は、理由（cannot be read (ENOENT)、not a certificate …）とともに失敗します。他のファイルや項目のチェックは引き続き実行されます。
• **ノードのサーバー上で実行してください。**ファイルはローカルディスクから読み取られます。REST API ではファイルを確認できないため、MCP ツールでは実行できません。相対パスは現在のディレクトリを基準に解決されます。cron はホームディレクトリでコマンドを開始するため、そこで絶対パスを指定してください。
• **秘密鍵は絶対に渡さないでください。**内容に PRIVATE KEY（すべての PEM 秘密鍵に付くラベル）が含まれるファイルは解析されず、a private key was passed; pass the certificate (.crt.pem) として失敗します。証明書でないファイルは、それ以外の場合も not a certificate として失敗します。どちらの場合も、レポートに含まれるのは指定したパス、判定結果、notAfter（ISO 8601、UTC）、残り日数、SHA-256 フィンガープリント、および JSON の場合はサブジェクトのコモンネームのみです。ファイルの他の内容は表示されません。
• --format json は、実行時に certificate 項目へ files: [{ path, status, notAfter, daysLeft, fingerprint256, commonName, reason }] を追加します（reason はファイルを使用できなかった理由を示し、それ以外の場合は null です。期限切れになると daysLeft は負の値になります）。
• 実行中にノードが応答を停止し、ノードに依存するすべての項目がその理由で失敗した場合、ファイルの状態にかかわらず終了コードは 3 のままです。その場合も certificate の行は出力されます。同様に、起動時に /node/info を読み取れない場合（ノードが応答しない、またはエラーを返す場合）も、ファイルは読み取られて同じように判定され、レポートが出力されます。--quiet を指定した場合も同じです。最初の行には ERROR とネットワーク名 unknown が表示され、ノードに問い合わせる 5 つの項目は理由 /node/info could not be read at start-up, so this check did not run とともにスキップされます。続いて certificate 項目と各ファイルの行が出力され、/node/info を読み取れなかった理由は stderr に表示されます。--cert を指定しない場合は、stderr に行が出力されるだけです。設定エラー（環境変数が未設定または無効、あるいはノードが別のネットワークにある場合）が発生すると、ファイルを読み取る前にチェックが終了します。

セキュリティ

• 読み取り専用です。 ツールがトランザクションに署名、構築、または通知することはありません。秘密鍵、ニーモニック、トークンを受け取る引数はありません。64 文字の 16 進数のアカウント引数は公開鍵として扱われ、このマシン上でアドレスに変換されてから、ノードにそのアドレスを照会します。誤って貼り付けた秘密鍵がノードに届くことはなく、エラーに表示されるのは最大でも先頭 8 文字です。SYMBOL_STATE_DIR が設定されている場合、保存するモード（compare_and_save、save_only）の symbol_harvesting_status が、ノードごとのロック解除済みハーベスター公開鍵、ブロック高、時刻のスナップショットをそのディレクトリに保存することを除き、呼び出し間で何も保存されません（秘密情報は含まれません。最初からやり直すにはファイルを削除してください）。
• 証明書ファイルを読み込むのは要求された場合のみです。 MCP サーバーは証明書も鍵も読み込みません。読み込むのは check --cert <path> を実行した場合のみで、実行するマシン上にある、そこで指定されたファイルだけです。独自に鍵ファイルを開くことはなく、誤って渡された PEM 秘密鍵（内容に PRIVATE KEY を含むファイル）は解析せずに拒否されます。ファイルから出力されるのは証明書の有効期限、SHA-256 フィンガープリント、コモンネームだけで、情報が外部に送信されることはありません。
• 接続先は固定されています。 サーバーが接続するのは SYMBOL_NODE_URL と、symbol_network_compare および symbol_version_drift の場合は SYMBOL_REFERENCE_NODES に列挙されたホストだけです。ツールに URL を引数として渡すことはできないため、モデルがリクエスト先を変更することはありません。テレメトリーはありません。
• 信頼できないチェーンデータです。 トランスファーメッセージ、メタデータ値、エイリアス名、ノードが自らについて報告する情報（フレンドリー名、ホスト名、ステータス、バージョン文字列）は、第三者が書き込んだものです。これらは、その性質が明らかになる名前（messageText など）で公開され、1 行に整形されます。タブと改行はスペースに置き換えられるため、単語の間隔は保たれ、連続するスペースは 1 つになります。それ以外の制御文字や不可視の書式文字（ゼロ幅文字や双方向制御文字、ソフトハイフン、そして人には見えなくてもモデルには読み取れる U+E0000〜U+E007F のタグ文字）はすべて削除され、文字を分割しない形で長さが制限されます。異体字セレクターは保持されるため、絵文字や漢字の異体字はそのまま残ります。ゼロ幅接合子で結合された絵文字は、個別の絵文字として出力されます。このようなテキストを表示する 16 個のツールは、そこから削除された文字数を invisibleCharactersRemoved で報告し、削除された文字がある場合は、その旨を示す行がサマリーの末尾に追加されます。summary では、このようなテキストはラベルの後に二重引用符で囲んで表示され、引用符とバックスラッシュは JSON と同様にエスケープされます（untrusted message: "…", friendlyName "…"）。そのため、引用符を閉じてサーバー自身の言葉として読ませることはできません。名前空間の文法に適合するエイリアス名と名前空間名は、そのまま表示されます。これらすべては指示ではなくデータとして扱ってください。
• 問題は明確に報告されます。 ネットワークの不一致（SYMBOL_NETWORK とノードの不一致）、ノードに到達できない場合、または予期しない応答形式の場合は、復旧のヒントを含むエラーとなり、別のネットワークへのサイレントフォールバックは行われません。スタックトレースや未加工の HTTP ボディがモデルに返されることはありません。
• リクエストの安全対策です。 リクエストごとのタイムアウトと User-Agent、ボディのストリーミング中に適用される 5 MB の応答サイズ上限（宣言された Content-Length がこれを超える場合、読み込み前に拒否）、ノードごとの最大 4 件の同時リクエスト、すべての応答に対するスキーマ検証を行います。リダイレクトは一切追跡されません。HTTP 3xx を返すノードにはエラーが返され、リダイレクト先のアドレスには接続しません。リクエストパスに含められるのは通常の識別子のみです。
• リポジトリの設定です。 CodeQL コードスキャン、プッシュ保護付きのシークレットスキャン、Dependabot（セキュリティ更新と月次のバージョン更新のグループ化）、main のブランチ保護（すべての変更はプルリクエストを経由して取り込まれ、履歴はリニアに保たれます）、非公開の脆弱性報告が有効になっています。

脆弱性の報告については、SECURITY.md を参照してください。

プライバシーポリシー

MCP サーバーとその check コマンドが送信する情報、受信者、そしてお使いのマシンにとどまる情報について説明します。

• このプロジェクト。 メンテナーが受け取る情報はありません。サーバーにはテレメトリー、アナリティクス、アップデートの確認機能はありません。サーバーが開くネットワーク接続は、SYMBOL_NODE_URL と SYMBOL_REFERENCE_NODES に設定したノードへの接続のみです。
• SYMBOL_NODE_URL のノード。 検索した情報を受け取ります。アドレス、トランザクションハッシュ、ネームスペース ID とモザイク ID、高さとエポックのほか、検索のページング、ソート順、フィルターのオプションです。ノードの運用者は、これらに加えて、リクエストの時刻と送信元 IP アドレスを確認できます。
• 名前と公開鍵。 ネームスペース名は、お使いのマシン上で計算された ID として送信されます（名前が隠れるわけではありません。ID は名前から導き出されます）。公開鍵で指定されたアカウントは、その公開鍵から導き出されたアドレスで照会されます。公開鍵を送信するツールが 1 つあります。symbol_delegation_diagnose は、アカウントについてノードが報告した公開鍵を同じノードに送り返し、そのアカウントの委任リクエストを検索します。
• SYMBOL_REFERENCE_NODES のノード。 /node/info と /chain/info のリクエストのみを受け取るため、ノードの運用者にはリクエストの時刻と IP アドレスが見えますが、検索した情報は見えません。これらのノードと SYMBOL_NODE_URL へのすべてのリクエストには、次のヘッダーが含まれます。 User-Agent: symbol-mcp-server/<version>
• お使いのディスク。 SYMBOL_STATE_DIR を設定した場合に限り、保存される各スナップショット（symbol_harvesting_status の compare_and_save または save_only モード、および check の各実行結果）は、ノードごとに 1 つのファイルに保存されます。ファイルには、ノードの nodePublicKey と、最新 60 件のスナップショットについて、時刻、高さ、ロック解除済みハーベスターの公開鍵が記録されます。ファイル（名前は harvesters- で始まります）は削除するまで残り、削除するとサーバーが保持していたすべてのスナップショットが消去されます。
• ログ。 サーバーと check は、数行のログを stderr に出力します。サーバーの起動行（バージョン、ネットワーク、ノードのホスト、設定されている場合はタイムゾーン、参照ノードの数、状態ディレクトリ）、起動失敗、引数の誤り、MCP ホストへの接続エラー、予期しないエラー、日付として表示できないノード時刻の各行、および check の診断情報です。ログファイルは作成せず、上記のスナップショットを除き、ツール呼び出しの記録も保持しません。stderr の扱いは、これらを起動したプログラムによって決まります（トラブルシューティングを参照）。
• check --cert。 指定した証明書ファイルは、コマンドを実行するマシン上で読み取られ、その内容は保存も送信もされません。レポートには、指定したパス、証明書の有効期限、SHA-256 フィンガープリントが表示され（--format json の場合はコモンネームも表示されます）、stdout に出力されます。その後の出力先（cron のメールやログファイルなど）は、ご自身の設定によります。
• このサーバーの外部。 サーバーが MCP ホストに返す回答には、チェーンデータと、お使いの設定値（ノード URL、参照ノード URL、タイムゾーン、リクエストのタイムアウト、スナップショットモードの場合はスナップショットファイルのパス）が含まれます。ホストとモデルのプロバイダーが質問と回答をどのように扱うか、また、パッケージの取得時（上記の npx 設定では起動のたびに npx が実行されます）やバンドルのダウンロード時に npm と GitHub が確認できる情報は、それぞれのポリシーによって定められています。
• お問い合わせ。 イシュートラッカーのいずれかの方法をご利用ください。イシューは公開されるため、公開したくない情報は記載しないでください。脆弱性またはプライバシー上の問題は、代わりに SECURITY.md に記載された非公開の報告方法でお知らせください。

リリースの完全性

• CI から出所情報付きで公開します。 すべての npm リリースは、GitHub Actions ワークフロー release.yml によってビルドおよび公開されます。公開には npm の信頼された公開（OIDC）を使用します。メンテナーのマシンにも、リポジトリのシークレットにも npm トークンはありません。各バージョンには、そのバージョンをビルドしたソースコミットとワークフロー実行に紐づく出所証明が付属します。

• ご自身で確認できます。

  • npmjs.com のパッケージページには、コミットとワークフロー実行が表示された Provenance セクションがあります。
  • npm view symbol-mcp-server dist.attestations を実行すると、最新バージョンの証明書 URL と出所述語の種類が表示されます。
  • インストールしたプロジェクトで npm audit signatures を実行すると、インストール済みパッケージのレジストリ署名と出所証明を検証できます。

• GitHub Releases には同じパッケージが含まれます。 0.8.0 以降の各 GitHub Release には、3 つのファイルが添付されています（それ以前のリリースには最初の 2 つが含まれます）。symbol-mcp-server-<version>.tgz は npm が提供する tarball とバイト単位で同一のファイルです（SHA-512 をレジストリの dist.integrity と照合します）。symbol-mcp-server-<version>.tgz.sigstore.json は、その tarball に対する npm の SLSA 出所証明を Sigstore バンドルとして格納したもので、subject が tarball の SHA-512 と一致することを検証します。さらに、Claude Desktop バンドル symbol-mcp-server-<version>.mcpb も含まれます（次の項目を参照）。最初の 2 つは scripts/release-assets.sh で収集されます。GitHub CLI を使ってダウンロードした 2 つのファイルを検証するには、次のコマンドを実行します。

  gh attestation verify symbol-mcp-server-<version>.tgz \
    --bundle symbol-mcp-server-<version>.tgz.sigstore.json \
    --repo inotakeh/symbol-mcp-server --digest-alg sha512
  

  npm の出所証明では tarball が SHA-512 で示されるため、--digest-alg sha512 が必要です。

• Claude Desktop バンドルは、同じ tarball からビルドされます。 symbol-mcp-server-<version>.mcpb は、上記の検証済み npm tarball と、そのリリースのロックファイルに基づき npm ci --omit=dev でインストールした本番用依存関係から、scripts/build-mcpb.sh を使って作成されます。それ以外のものはコンパイルもダウンロードもされません。リリースワークフローは、このバンドルに GitHub のビルド出所証明を添付します（gh attestation verify … --repo inotakeh/symbol-mcp-server。インストールを参照）。

• リリースできるユーザー。 リリースタグ（v1.2.3）を作成できるのはメンテナーのみです。ワークフローはまず、メンテナーが実行を承認するまで npm-publish GitHub Environment で待機します。承認後にのみ、タグが package.json およびその他のリリースファイルと一致することを確認し、lint、型チェック、テストを実行してから公開します。手順の全容は docs/RELEASING.md に記載されています。

対応ネットワーク

ネットワーク	識別子	生成ハッシュシードによる検出
Symbol メインネット	104	57F7DA20…72B2D6
Symbol テストネット（sai）	152	49D6E1CE…FC665A4

起動時にノードからネットワークを検出します。その他の生成ハッシュシード（プライベートネットワーク、NEM NIS1）は拒否されます。両ネットワークのノードは https://nodewatch.symbol.tools/ に掲載されています。ノードの選択を参照してください。

制限事項

• ノードの履歴と制限。 結果は設定したノードから取得されます。トランザクション履歴を刈り込むノードでは、保持されているものだけが返されるため、そのようなノードでは symbol_transaction_search で古いトランザクションを見つけられない場合があります。また、パブリックノードでは受け付けるリクエスト数が制限されている場合があります。リクエスト数が最も多い呼び出しは symbol_account_rank（最大50ページ）と、長期間を対象とする symbol_harvesting_income（最大200ページ）です。これらにはご自身のノードを使用してください。
• 未来の日付は推定値です。 投票キー、ネームスペース、モザイクの有効期限、および将来の高さやエポックは、直近10,000ブロック（メインネットでは約30秒）における実測平均ブロック時間から予測され、推定値として示されます。
• 暗号化されたメッセージは復号されず、 暗号化済みとして報告されます。
• ページサイズは10～100です。 catapult-rest が10未満のページサイズを10に補正するためです。
• 検索対象は承認済みトランザクションのみです。 未承認および部分トランザクションは、ハッシュを指定して symbol_transaction_get から確認できます。
• ハーベスティング状況の対象は設定済みノード（/node/unlockedaccount）であり、ネットワーク全体ではありません。
• 価格は取得しません。 symbol_holdings_value は残高に呼び出し元が渡した単価を掛け合わせます。価格の取得、確認、記憶は行わず、結果の精度は入力された価格次第です。価格を先に調べ（ウェブ検索、価格情報を提供する MCP サーバー、またはユーザーへの確認など）、priceSource と priceAsOf を添えて渡してください。値は単純な積であり、手数料、スプレッド、税金は含まれず、税務上の取得単位ごとの計算も行いません。
• 保有者順位はインデックスではなくスキャンです。 symbol_account_rank は maxRank（最大5,000、つまり50リクエスト）まで、リクエストごとに100アカウントずつ保有者リストを読み込みます。その順位より下のアカウントには rank: null と rankBeyond が返されます。残高が同じ場合の並び順はノードによって異なり、呼び出しごとに入れ替わることがあります。
• ハーベスターの履歴はローカルに保存されます。 symbol_harvesting_status は、SYMBOL_STATE_DIR の下に自身で保存したスナップショットと比較します。別のマシンを使う場合、ファイルを削除した場合、ノードキーを変更した場合（移行後の新しい node.key.pem など）は、新しい基準からの記録になります。同じ日に繰り返し呼び出すとスナップショットもその都度追加され、保持されるのは最新60件のみです。
• ハーベスティング収入の呼び出し1回あたりの読み取り上限は明細20,000件（100件ずつ200ページ）です。これを超える期間は truncated となるため、fromHeight／toHeight で分割してください。報酬は HarvestFee レシートを合計します。そのため、レシートを刈り込むノードでは、チェーンに記録されている額より少なく報告されます。
• 1年分のハーベスティング収入は分割して読み取ります。 catapult-rest は広い高さ範囲への応答に時間がかかるため、範囲は約90日ごとのチャンクに分割され、順番に読み取られます。チャンクの最初のページがタイムアウトした場合は、約7日まで範囲を半分にして再試行します。合計値は1回のクエリで得られる値と同じです。fetch フィールドには範囲の読み取り方法が示されます。SYMBOL_REQUEST_TIMEOUT_MS 内に約7日分を応答できないノードを使った場合にのみ、呼び出しは失敗します。
• ファイナリティへの参加状況では、ノードが保持している証明を読み取ります。 unavailable は、そのエポックの証明がノードにないこと（まだファイナライズされていないか、ノードが保持する履歴の範囲外であること）を意味し、アカウントが投票しなかったことを意味するものではありません。サーバーは登録済み投票者数を把握していないため、signatureCount は nodewatch などの外部リストとのみ比較できます。
• バージョン差異の確認は一部のサンプルであり、全数調査ではありません。 symbol_version_drift が確認するのは、設定済みノードが現在把握しているピアと参照ノードであり、ネットワーク全体ではありません。全体像は nodewatch で確認できます。symbol_node_status のクロックスキューと最新ブロックの経過時間は、このサーバーを実行しているマシンの時計を基準に測定されるため、その時計自体がずれている可能性もあります。
• メインネットとテストネットのみです。 設計上、トランザクションの構築、署名、アナウンスは行いません。
• URL は指定されたとおりに使用されます。 サーバーがポートやスキームを自動で切り替えることはありません。ノードが http のポート3000でのみサービスを提供している場合、localhost 上にない限り使用できません。

トラブルシューティング

起動時のエラーは、symbol-mcp-server failed to start: で始まる1行として stderr に出力されます。MCP ホストは stderr をログに保存します（Claude Desktop の場合、macOS では ~/Library/Logs/Claude/mcp*.log、Windows では %APPDATA%\Claude\logs）。同じコマンドをターミナルで実行してもエラーが表示されます。

表示される内容	原因と対処方法
SYMBOL_NODE_URL is required	変数がサーバープロセスに渡されていません。ホストの設定の env ブロックに記述してください。シェルで export しても、デスクトップアプリが起動するサーバーには渡されません。
SYMBOL_NODE_URL must use https:// または SYMBOL_NODE_URL must start with https://	ノードの https:// URL を使用してください（通常はポート 3001）。http:// が許可されるのは localhost／127.0.0.1／[::1] のみです。
SYMBOL_NETWORK=mainnet but node <host> is on testnet	ノードが別のネットワーク上にあります。SYMBOL_NODE_URL を使用したいネットワークのノードに向けるか、SYMBOL_NETWORK を修正してください。
Node <host> reports an unknown network	ノードのジェネレーションハッシュシードが Symbol の mainnet または testnet のいずれでもありません（プライベートネットワーク、または NEM NIS1 ノードです）。Symbol の mainnet または testnet ノードを使用してください。
起動時に <host> did not answer /node/info within 10000 ms または could not reach <host> for /node/info が表示される。ツールからは Node <host> did not answer … within … ms または Could not connect to node <host> が表示される	ノードが停止している、過負荷になっている、またはポートが間違っています（https の場合は 3001）。nodewatch の別のノードを試すか、SYMBOL_REQUEST_TIMEOUT_MS を設定して低速のノードに時間を与えてください（最大 600000）。
起動時に <host> answered /node/info with a redirect (HTTP 301), which is not followed が表示される。ツールからは Node <host> answered … with a redirect が表示される	URL がリダイレクト先（http から https、プロキシ、または移動したパス）を指しています。リダイレクトはたどられず、リダイレクト先のアドレスにも接続されません。SYMBOL_NODE_URL をノードの REST API URL（通常は https://<node-host>:3001）に設定してください。
ツールから Node <host> does not provide the endpoint … (no such route) が表示される（check では hint: 行として表示される）	ノードから、そのパスに対応するルートがないという応答がありました。このサーバーには API ノードの REST API が必要です。原因として、Light REST のみを提供するノード（少数の /node および /chain エンドポイントのみを提供します。ノードの選択を参照）、または該当エンドポイントのないバージョンの catapult-rest を実行しているノードが考えられます。SYMBOL_NODE_URL を最新の API ノードの REST URL（たとえば nodewatch に掲載されているもの）に設定してください。最新の API ノードがこの応答を返す場合は、このサーバーのバグです。ツール名を添えて報告してください。
ツールから Node <host> answered HTTP 429 for …（または 503）が表示される	ノードが受け付けるリクエスト数を制限しているか、過負荷になっています。しばらく待ってから再試行してください。多数のページを読み取る呼び出し（symbol_account_rank に大きな maxRank を指定する場合、長期間の symbol_harvesting_income など）には、自分のノードまたは nodewatch の別のノードを使用してください。
Claude Desktop に symbol_* ツールが表示されない	バンドル（.mcpb）の場合：拡張機能の設定を開いてください。Symbol node URL が空の場合、拡張機能は起動しません。JSON 設定の場合：Claude Desktop が設定を読み込むのは起動時のみです。アプリを完全に終了して（ウィンドウを閉じるだけでは不十分です）、再度開いてください。それでもツールが表示されない場合は、上記のログで failed to start の行を探し、JSON が有効か確認してください。
npm warn EBADENGINE Unsupported engine（npm の出力）	Node.js のバージョンが 22 より古いです。node --version を確認し、22 以降をインストールしてください（例：nvm install 22）。デスクトップアプリがシェルとは異なる PATH 上の node／npx を見つける場合があります。必要に応じて command にフルパスを指定してください。
リリース後も古いバージョンが実行される	npx はキャッシュを再利用します。npx -y symbol-mcp-server@latest --version を実行するか、args に symbol-mcp-server@latest を指定してください。

開発

npm ci
npm run lint && npm run typecheck && npm test
npm run build
SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js
npx @modelcontextprotocol/inspector -e SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<testnet-node>:3001 npm test   # live-node tests
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<node-host>:3001 SYMBOL_INTEGRATION_ACCOUNT=<address> npm test   # account tools against a specific account
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<node-host>:3001 SYMBOL_INTEGRATION_MULTISIG_ACCOUNT=<address> npm test   # symbol_account_get against a multisig account and its first cosignatory
node scripts/capture-fixtures.mjs https://<node-host>:3001   # refresh test/fixtures/<network>/ from a node

MCP Inspector が起動するサーバーに渡す環境変数は、MCP SDK のデフォルトである PATH や HOME などの一部と、明示的に渡したものだけです。そのため、npx の前に設定した変数は サーバーに引き継がれません。上記のように -e KEY=VALUE で各変数を渡すか、Inspector の フォームに入力してください。macOS と Linux では、サーバーコマンドを env で囲む方法も使えます。

設計ノート：docs/DESIGN-BRIEF.md。変更履歴：CHANGELOG.md。 リリース：docs/RELEASING.md。

コントリビューション

バグ報告、機能リクエスト、プルリクエストを歓迎します。開発環境のセットアップ方法、ツールの追加方法、 設計ルールについては CONTRIBUTING.md をご覧ください。セキュリティ上の問題は SECURITY.md を通じてご報告ください。

ライセンス

MIT