mina-mcp-server

Name: mina-mcp-server
Author: MinaProtocol

ローカル

github.com/MinaProtocol金融データ022 週間前に更新

リポジトリ

mina-mcp-server について

mina-mcp-serverは、Mina Protocolのアカウント、ブロック、トランザクション、zkApp、アーカイブSQL、RosettaデータをAIアシスタントやMCPクライアントに提供します。Liveモードはローカル環境なしで公開ネットワークを読み取り、tutorialとsnapshotモードはローカルチェーン実験やアーカイブ分析に使えます。

主な機能

0140種類以上のブロックチェーン照会ツール
02live、tutorial、snapshotの3モード
03アカウント、ブロック、取引、zkAppデータの照会
04Rosetta Data APIによる照会
05アーカイブDBへの読み取り専用SQL
06tutorialモードのテストアカウント用フォーセット

活用シーン

01公開Minaネットワークの口座とブロックの照会
02zkAppイベントとアクションの分析
03過去のアーカイブデータへのSQL実行
04ローカルlightnetでの読み書きフローのテスト

MCP 対応

MCPを通じて、Minaネットワークのデータと操作ツールをクライアントに提供します。Liveモードは公開ネットワークへの照会を中継し、tutorialモードはローカルlightnetでの読み書き、snapshotモードはアーカイブSQL照会に対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "minaprotocol-mina": {
      "command": "npx",
      "args": [
        "-y",
        "@o1-labs/mina-mcp-server"
      ]
    }
  }
}

起動コマンドnpx -y @o1-labs/mina-mcp-server

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npm@o1-labs/mina-mcp-server0.7.3stdio

ツール

掲載時のツール一覧 · 3 週間前に更新

パラメーター	型	必須	説明
token	string	いいえ	Token ID（省略可。デフォルトは MINA）
publicKey	string	はい	Mina 公開鍵（B62...）

詳細

mina-mcp-server

Mina Protocol ブロックチェーン向けの MCP（Model Context Protocol）サーバーです。Mina ブロックチェーンのデータと操作を、AI アシスタントやその他の MCP クライアントが利用できる、MCP 互換ツールを通じて公開します。

初めての方へ： どのモードを使えばよいですか？ → MCP クライアントを接続する → 動作を確認するに進んでください。コピーして使えるプロンプトについては、プロンプト集をご覧ください。

ステータス：ベータ／プレビュー。 Live モードはパブリックな Mina ネットワーク（devnet／mainnet／mesa）に接続し、ローカルのインフラは不要です。npx @o1-labs/mina-mcp-server --mode live --network devnet を実行するか、ホスト型サンドボックスをクライアントに指定してください。Snapshot モードと tutorial モードは、基盤サービス（PostgreSQL、および tutorial モードではローカルの Mina lightnet）を利用する薄い MCP レイヤーです。これらは事前にご自身で起動する必要があります。詳しくは前提条件をご覧ください。インフラ不要で snapshot モードを利用できる、同梱の SQLite スナップショットは現在計画中です（#28）。

機能

アカウント、ブロック、トランザクション、zkApp のイベント／アクション、ネットワーク／同期ステータス、Rosetta、アーカイブ SQL を照会する 40 以上の MCP ツール。
3 つの動作モード：
- Live — パブリックな Mina ネットワーク（devnet／mainnet／mesa）への読み取り専用プロキシです。ローカルのインフラは不要で、セットアップなしですぐに使えます。
- Tutorial — ローカルの Mina lightnet（デーモン、アーカイブ、テストアカウント用ファウセット）に対する、読み書き可能な環境です。
- Snapshot — 凍結されたアーカイブ PostgreSQL ダンプに対する、スキーマ限定の SQL アクセス（query_archive_sql、get_archive_schema）です。
ネイティブ GraphQL ツールに加え、標準化された Rosetta Data API ツールを利用できます（live モード）。
安全な SQL アクセス — タイムアウト保護付きで、アーカイブ DB に対して読み取り専用クエリを実行します。
テストアカウント用ファウセット — 事前に資金が入ったアカウントを取得／解放できます（tutorial モード）。
プロンプト集 — ツールをエンドツーエンドで連続実行する、コピーして使えるプロンプトです。

どのモードを使えばよいですか？

目的	モード	必要なインフラ
パブリックネットワークを照会する（残高、ブロック、zkApp イベント、Rosetta）	`live`	不要 — `npx` のみ。まずはこちらから。
自分の鍵を使ってパブリックネットワークでトランザクションを送信する	`live` + `--wallets`	不要（鍵はプロセス内で署名されます）
制御可能なチェーン上で開発する（ファウセット、リセット、書き込み）	`tutorial`	ローカルの Mina lightnet（前提条件）
過去のアーカイブダンプに対して分析 SQL を実行する	`snapshot`	PostgreSQL アーカイブダンプ（前提条件）

ほとんどの方には live がおすすめです。Node 以外にインストールするものはありません。

MCP クライアントを接続する

ローカル（推奨）、npx 経由 — クローンもインフラも不要です：

{
  "mcpServers": {
    "mina": {
      "command": "npx",
      "args": ["-y", "@o1-labs/mina-mcp-server", "--mode", "live", "--network", "devnet"]
    }
  }
}

devnet を mainnet または mesa に置き換えてください。その他のモードでは、--mode を変更し（--network は削除します）、Configuration を参照してください。

ホスト型サンドボックス（インストール不要）— クライアントに URL を指定します：

{ "mcpServers": { "mina": { "url": "https://mina-mcp-sandbox.fly.dev/mcp" } } }

ホスト型サンドボックスは、共有 lightnet 上でチュートリアルモードを実行します（ベストエフォートで、SLA はありません）。実際のネットワークでは、ローカルの live モードを使用してください。

クライアント別の設定ファイルの場所：

クライアント	設定	備考
Claude Desktop	`claude_desktop_config.json`（Settings → Developer）	上記と同じ `command`／`args` の形式
Claude Code	プロジェクト内の `.mcp.json`、または `claude mcp add`	同じ形式
Cursor	`~/.cursor/mcp.json`（または Settings → MCP）	同じ形式
Cline / Roo	拡張機能の MCP 設定 JSON	同じ形式
Windsurf	`~/.codeium/windsurf/mcp_config.json`	同じ形式
Continue	`mcpServers` 配下の `~/.continue/config.json`	同じ形式
Zed	`context_servers` 配下の `settings.json`	Zed では `"command": { "path": "npx", "args": [...] }` を使用します

Zed 以外のすべてのクライアントでは、同じ { command, args } オブジェクトを使用します。異なるのはファイルの場所だけです。ホスト型 URL の設定は、リモート／ストリーマブル HTTP MCP サーバーに対応するすべてのクライアントで動作します。

動作を確認する

接続したら、アシスタントに次のように尋ねてください。

「現在の Mina ネットワークの状態を説明してください。」

describe_state が呼び出され、syncStatus（例：SYNCED）、ネットワーク名、メンプールのサイズを含むスナップショットが返されます。これが正常に動作している合図です。（mesa では、ヒントに PREFLIGHT の注意書きが表示されます。）

設定

すべてのフラグには環境変数での指定方法があります。全オプションについては npx @o1-labs/mina-mcp-server --help を実行してください。

$ mina-mcp-server --help
USAGE
  mina-mcp-server [--mode <mode>] [options]

MODES
  live        Read-only proxy to a public network. No local infra. (use --network)
  tutorial    Read+write against a local Mina lightnet (daemon + archive + faucet).
  snapshot    Schema-only SQL access against a frozen archive Postgres dump. (default)

フラグ	環境変数	値（デフォルト）
`--mode`	`MINA_MCP_MODE`	`live` / `tutorial` / `snapshot`（`snapshot`）
`--network`	`MINA_MCP_NETWORK`	`devnet` / `mainnet` / `mesa` / `mesa-mut`（`live` のみ）
`--transport`	`MINA_MCP_TRANSPORT`	`stdio` / `http`（`stdio`）
`--wallets`	`MINA_MCP_WALLETS`	`wallets.json` のパス（ライブ書き込み）
`--allow-mainnet-writes`	`MINA_MCP_ALLOW_MAINNET_WRITES=1`	mainnet への送信を許可するオプトインゲート
(http only)	`MINA_MCP_HTTP_PORT`	`--transport http` のポート（`3000`）
`--help`、`--version`	—	ヘルプ／バージョンを表示して終了

トラブルシューティング

症状	解決方法
`npx` が失敗する／「Unsupported engine」と表示される	Node ≥ 20.18 が必要です。`node --version` で確認してください。
`tutorial`／`snapshot` でツールが「not reachable」を返す	サーバーはインフラを起動しません — 先に lightnet／Postgres を起動してください（Prerequisites）。
ポートがすでに使用中（`tutorial` の lightnet）	別の lightnet／デーモンが 3085／8282／5432 にバインドされています。停止するか、ポートを変更してください。
ソースを編集しても変更が反映されない	`npm run build` を再実行してください（クライアントが実行するのは `src/` ではなく `dist/` です）。
ホスト型サーバー：「Missing/!Unknown session id」	クライアントはすべてのリクエストで、`initialize` の `Mcp-Session-Id` ヘッダーを引き継ぐ必要があります — ストリーマブル HTTP MCP に対応するクライアントを使用してください。
`mesa` のデータが不安定に見える	`mesa` はプレフライトネットワークです — 通知なくリセットされたり、名前が変更されたりすることがあります。データは一時的なものとして扱ってください。

前提条件

tutorial モードと snapshot モードでのみ必要です。live モードでは必要ありません。

共通：

Node.js >= 20.18
Docker と Docker Compose（以下のバックエンドサービスを実行するため）

Snapshot モードで追加で必要なもの：

コンポーネント	用途	デフォルトのエンドポイント
Mina アーカイブスキーマとデータを含む PostgreSQL	すべての読み取りクエリのソース	`localhost:5432`

リポジトリに含まれる docker-compose.snapshot.yml を使って起動できます。./snapshots/devnet-latest にあるスナップショットダンプ、または compose の download プロファイル経由でダウンロードしたダンプが必要です。

Tutorial モードで追加で必要なものは、完全なローカル lightnet です。

コンポーネント	用途	デフォルトのエンドポイント
Mina Daemon GraphQL	ライブのチェーンクエリ、送金	`http://localhost:3085/graphql`
Archive-Node-API	zkApp のイベントとアクション、アーカイブブロック	`http://localhost:8282`
Accounts Manager	テストアカウント用フォーセット	`http://localhost:8181`
PostgreSQL（アーカイブ DB）	読み取りクエリ	`localhost:5432`

4 つすべてが docker-compose.tutorial.yml によって起動します。ツールが正常に応答するまで、ネットワークの同期に約 1～2 分かかります。

注： npm（npx @o1-labs/mina-mcp-server）からインストールした場合、docker-compose ファイルは tarball に含まれていません。インフラを起動するには、このリポジトリをクローンするか、docker-compose.*.yml ファイルをコピーする必要があります。

クイックスタート

# Install dependencies
npm install

# Build
npm run build

# Start infrastructure (pick one):

# Option A: Snapshot mode (read-only, from local dump)
SNAPSHOT_DIR=./snapshots/devnet-latest docker compose -f docker-compose.snapshot.yml up -d

# Option B: Snapshot mode (download latest dump from GCS — devnet by default)
docker compose -f docker-compose.snapshot.yml --profile download up -d
#   See "Snapshot mode against other public networks" below for mainnet/mesa.

# Option C: Tutorial mode (full lightnet)
docker compose -f docker-compose.tutorial.yml up -d
# Wait ~1-2 min for the network to sync

# Option D: Live mode (read-only, talks to a public Mina network — no local infra)
#   Picks a network with --network (devnet, mainnet, mesa). Nothing else to start.

# Run the MCP server
MINA_MCP_MODE=snapshot npm start                              # or
MINA_MCP_MODE=tutorial npm start                              # or
npm start -- --mode live --network devnet                     # no Postgres / lightnet needed

公開 Mina ネットワークに対する Live モード

Live モードは読み取り専用の薄いプロキシで、MCP ツール呼び出しを o1Labs がホストする公開エンドポイントへの GraphQL/HTTP リクエストに変換します。ホストするものはありません。MCP クライアントの隣でローカルに実行してください。

npm start -- --mode live --network devnet     # or mainnet, mesa
# equivalently:
MINA_MCP_MODE=live MINA_MCP_NETWORK=devnet npm start

エンドポイントは SLA のないベストエフォート型のサービスであり、URL は変更される場合があります。ネットワークは安定性ティアによって分類されています。

ネットワーク	安定性	意味
`devnet`	安定	長期稼働する開発ネットワークです。継続して利用できる見込みです。
`mainnet`	安定	本番環境です。継続して利用できる見込みです。
`mesa`	事前検証	プレビュー／ステージングネットワークです。予告なくリセット、改名、または廃止される場合があります。エンドポイント、アーカイブダンプのファイル名、さらにはネットワーク自体の識別情報も、安定しているとは限りません。
`mesa-mut`	事前検証	Mesa Upgrade Test — Mesa ハードフォークのリハーサル用に用意された mainnet 状態のフォークです。アップグレードのリハーサルに紐づいており、予告なくリセットまたは廃止されます。ジェネシスは mainnet 状態のフォークですが、デーモンは networkID `mina:testnet`（testnet 署名スキーマ）を報告します。Rosetta エンドポイント、フォーセット、公開済みのアーカイブダンプはなく、snapshot モードは利用できません。

LiveProvider を事前検証ネットワークに対して構築すると、サーバーは起動時に [WARN] Network '<name>' is a PREFLIGHT network… という行を出力し、describe_state の hints[] の先頭に PREFLIGHT の注意書きを追加します。そのため、出力を利用する LLM はデータについて推論する前に注意事項を確認できます。事前検証ネットワークを使って下流の自動化を構築する場合、収集したデータは一時的なものとして扱い、安定したネットワークへのフォールバックを用意してください。

Rosetta Data API（ライブモード）

ライブモードのネットワークに Rosetta エンドポイントが設定されている場合（現在は devnet、mainnet、mesa に設定されており、mesa-mut には設定されていません）、サーバーはデーモン／アーカイブ関連のツールとともに、5 つの Rosetta Data API ツールを登録します。Rosetta エンドポイントのないネットワークでは、rosetta_* ツールは一切登録されないため、公開されるツール一覧には、そのネットワークで実際に利用できる機能が反映されます。これらのツールは標準化された Rosetta 形式で応答を返します。Rosetta に対応済みの LLM やインテグレーションで役立ちます。

ツール	Rosetta エンドポイント	用途
`rosetta_status`	`POST /network/status`	現在のブロック／ジェネシスブロック／最古のブロック、同期状態
`rosetta_account`	`POST /account/balance`	アドレスの残高。特定のブロックを指定することもできます
`rosetta_block`	`POST /block`	インデックスまたはハッシュを指定してブロック全体（オペレーションを含む）を取得
`rosetta_mempool`	`POST /mempool`	保留中のトランザクション識別子
`rosetta_mempool_transaction`	`POST /mempool/transaction`	保留中の単一トランザクションとそのオペレーション

Construction API（オフライン署名フロー）は、このツール群には意図的に含めていません。独自のツール設計（マクロとリテラルのどちらを使うか）を伴うため、今後対応する予定です。

各ネットワークには、MCP サーバー自身はプロキシしないものの、LLM が人間または Rosetta 対応クライアントに渡せるよう describe_state.hints[] で公開されるオプションの参照先もあります。

ネットワーク	フォーセット	Rosetta
`devnet`	https://faucet.minaprotocol.com	https://devnet-rosetta.gcp.o1test.net
`mainnet`	(なし — 取引所のみ)	https://mainnet-rosetta.gcp.o1test.net
`mesa`	https://faucet.minaprotocol.com	https://rosetta.mina-mesa-network.gcp.o1test.net
`mesa-mut`	(なし — mainnet の状態を引き継いだフォーク)	(なし)

Mesa ハードフォークのアップグレード追跡（`mesa-mut`）

mesa-mut はMesa ハードフォークのアップグレードをリハーサルします。--network mesa-mut を指定すると、サーバーは追加のツール get_upgrade_status を登録します。このツールは、アップグレードトラッカー（status.json）とライブデーモンの現在のグローバルスロットを組み合わせて、フェーズを報告します。報告内容には、現在のスロットと stopTransactionSlot／stopNetworkSlot の比較、残りのスロット数／分数、Mesa のジェネシスタイムスタンプ、フェーズを考慮した hints[] を含む transactionsOpen ブール値が含まれます。送信を行う前に transactionsOpen を確認してください。stopTransactionSlot 以降に送信されたトランザクションは破棄されます。

エージェントのワークフロー向けに、関連する Claude スキル（.claude/skills/mesa-upgrade）も用意されています。このスキルはこのツールを、フォーク前・実行中・実行後に行うべきこと／避けるべきことをまとめたフェーズ別の運用手順書で補います。

ライブ書き込みモード（実験的 — クライアント側署名）

ウォレットキーを1つ以上サーバーに渡すことで、ライブモードを読み取り専用から読み取り＋書き込みに切り替えられます。送信は mina-signer を使ってこのプロセス内で署名され、署名済みトランザクションとしてデーモンに送信されます。デーモン側にウォレットはなく、devnet/mainnet のファウセットもなく、キー情報がネットワーク上を流れることもありません。

npm start -- --mode live --network devnet --wallets ./wallets.json
# equivalently:
MINA_MCP_MODE=live MINA_MCP_NETWORK=devnet MINA_MCP_WALLETS=./wallets.json npm start

実験的機能 — 実際の資産に対して使用する前にお読みください。 ウォレットの秘密鍵は、ディスクから暗号化されずにこのプロセスのメモリに読み込まれます。devnet/mesa の一時的なテスト用ウォレットなら問題ありませんが、本番用の鍵には適していません。次のいずれかを選んでください。

失ってもよい金額だけが入ったウォレットのみを読み込む、または

mainnet ではこのモードを一切使用せず、重要な資産にはハードウェアウォレットまたはオフライン署名を使用する。

さらに、設定ミスへの意図的な歯止めとして、mainnet を対象にするには --allow-mainnet-writes（または MINA_MCP_ALLOW_MAINNET_WRITES=1）も必要です。

wallets.json のスキーマ

{
  "wallets": {
    "warm": {
      "keyPath": "/home/me/.mina/keys/warm.key",
      "publicKey": "B62q…",
      "caps": { "maxFeeNanomina": "100000000", "maxAmountNanomina": "5000000000" }
    },
    "demo": { "keyPath": "/home/me/.mina/keys/demo.key", "publicKey": "B62q…" }
  },
  "defaultWallet": "warm"
}

keyPath ファイルには、EK… 形式の base58check 秘密鍵がちょうど1つ含まれている必要があります（1行のみで、それ以外の内容は不可）。このリビジョンでは、暗号化された JSON キーファイルはサポートされていません。
keyPath ファイルのパーミッションは必ず chmod 600 にしてください。そうでない場合、ローダーは起動を拒否します。
起動時に、読み込まれた鍵と照合して publicKey を検証します。これにより、ツールの実行前に「このエイリアスに間違った鍵を設定した」というミスを検出できます。
caps（任意、ウォレットごと）は、1件のトランザクションに上限を設定します。maxFeeNanomina と maxAmountNanomina（10進数のナノMINA。1 MINA = 1e9）が指定できます。上限を超える送信は署名前に拒否されます。これは、暴走または敵対的な LLM によるウォレットの資金流出を防ぐ安全策です。メモの上限は常に32バイトです。
defaultWallet は任意です。省略した場合、すべての send_payment/send_delegation 呼び出しで from_alias または from を指定する必要があります。
パスは設定ファイルのディレクトリからの相対パスにできます（そのため、設定一式をまとめて移動できます）。

ライブ書き込みモードで追加されるツール（ライブモードの読み取りツールに加えて）：

ツール	説明
`list_wallets`	読み込まれたエイリアス、publicKeys、残高、nonce を表示します。秘密鍵は返しません。
`send_payment`	MINA の支払いに署名して送信します。`from_alias`、`from`（publicKey）、またはデフォルトを使用します。送信せずに署名済みペイロードを確認するには、`dry_run: true` を渡します。
`send_delegation`	ステーク委任用の、同じ形式のツールです。

ライブ書き込みモードの describe_state には wallets[] ブロック（エイリアス、publicKeys、残高。鍵は含みません）が追加され、Live-WRITE mode… のヒントが先頭に付加されます。これにより、LLM は最初の状況把握時に新しい機能を認識できます。

安全性の保証（文書上の説明にとどまらず、実際に強制されます）：

パーミッションゲート。 モードが 0600 より広く設定された鍵ファイルがあると、起動時に明確なエラーで失敗します。
mainnet 書き込みのオプトイン。 --network mainnet --wallets … には --allow-mainnet-writes が必須です。
nonce キャッシュ。 max(daemon_nonce, last_submitted+1) を使います。アーカイブの遅延との競合を乗り越え、送信に失敗した際に nonce を無駄に消費しません。
ドライラン。 send_payment(dry_run: true) は、デーモンにアクセスせずに署名済みペイロードと計算済みハッシュを返します。
自動的な秘匿情報の除去テスト。 test/mcp/wallets-redaction.test.ts は、登録済みのすべてのツールを無効な引数で実行し、サーバーに読み込まれた秘密鍵が応答に一切含まれないことを検証します。

他のパブリックネットワークでのスナップショットモード

docker-compose.snapshot.yml の --profile download パスは、パブリックバケット https://storage.googleapis.com/mina-archive-dumps からダンプを取得します。URL の形式は <prefix>-<YYYY-MM-DD>_<HOUR>.sql.tar.gz です。別のネットワークを対象にするには、ARCHIVE_DUMP_PREFIX を上書きします。

ネットワーク	プレフィックス	頻度	直近のサイズ
devnet（デフォルト）	`devnet-archive-dump`	毎日、UTC の `_0000`	圧縮時で約 370 MB
mainnet	`mainnet-archive-dump`	毎日、UTC の `_0000`	圧縮時で約 1.5 GB
mesa（事前検証用）	`hetzner-pre-mesa-1-archive-dump`	1 日 2 回、UTC の `_0000` と `_1200`	圧縮時で約 32 MB

# Mainnet snapshot
ARCHIVE_DUMP_PREFIX=mainnet-archive-dump \
  docker compose -f docker-compose.snapshot.yml --profile download up -d

# Mesa snapshot (preflight — see warning below)
ARCHIVE_DUMP_PREFIX=hetzner-pre-mesa-1-archive-dump ARCHIVE_DUMP_HOUR=1200 \
  docker compose -f docker-compose.snapshot.yml --profile download up -d

Mesa は事前検証用ネットワークです。 上記のダンププレフィックスは内部運用上の命名であり、安定した規則ではありません。mesa が正式運用に移行するか廃止される際、予告なく変更されたり公開が停止されたりする場合があります。mesa のスナップショットデータは一時的なものとして扱ってください。

ライブモードでは、サーバーは利用できないインフラを必要とするツールをすべて非表示にします。

アーカイブ Postgres がない場合 → query_archive_sql、get_archive_schema、list_blocks、search_transactions、get_transaction、get_staking_ledger、get_archive_stats は利用できません。
アカウントマネージャー／フォーセットがない場合 → faucet、return_account、reset_session は利用できません。
リセット用ジャニターがない場合 → freeze_reset、unfreeze_reset、freeze_status は利用できません。
パブリックデーモンは代理署名を行いません → send_payment、send_delegation、get_tracked_accounts は利用できません。

ライブモードの get_block には stateHash が必要です。まず Archive-Node-API の get_archive_blocks を使って取得してください。

デモ：チュートリアルモードでのエンドツーエンド決済

このサーバーを実行する目的は、通常なら半ダースもの個別の GraphQL 呼び出しが必要な複数ステップのオンチェーン処理を、1 つの自然言語プロンプトで実行できることです。lightnet が起動し、MCP クライアントが接続されていれば、次のプロンプトを実行できます。

フォーセットから残高のあるテストアカウントを 2 つ取得してください。最初のアカウントから 2 つ目に 10 MINA を送金し、ブロックに取り込まれるまでポーリングしてください。送信直後の mempool の状態と、取り込まれたブロックの高さを表示してください。確認後、両方の残高を確認し、2 つのアカウントを返却してください。

次のツールシーケンスが実行されます（実際のチュートリアルモード実行からの抜粋）。

ステップ	ツール	主な出力
1	`faucet` ×2	それぞれ 1550 MINA のアカウント 2 つ
2	`send_payment`（10 MINA、手数料 0.1）	Tx ハッシュ `5JtVaGBj…6Tto`
3	送信者でフィルタリングした `get_mempool`	保留中の tx を取得
4	`get_transaction_status`	`INCLUDED`
5	`get_transaction` → `get_block(height=175)`	ブロック 175（`3NKErr14…YHpm`）に含まれ、ステータスは `applied`
6	`get_account` ×2	送信者 1539.9 MINA、受信者 1560 MINA — 送信者は送金で −10、手数料で −0.1、受信者は +10 ✓
7	`return_account` ×2	両方ともプールに返却

同期済みの lightnet で、エンドツーエンドの所要時間は数秒でした。このフローでは、チュートリアル専用の各ツール群（フォーセット／返却、送金の送信、mempool、ステータスのポーリング、ブロック／アカウントの検索）を一度に実行するため、デプロイ後のスモークチェックに役立ちます。

インフラ設定（チュートリアル／スナップショット）

以下はバックエンドサービスの場所を設定するもので、live モードでは使用されません。.env.example を .env にコピーし、必要に応じて調整してください。

cp .env.example .env

主な変数：

変数	デフォルト	説明
`MINA_MCP_MODE`	`snapshot`	サーバーモード：`snapshot`、`tutorial`、または `live`
`MINA_MCP_NETWORK`	(未設定)	ライブモードで必須：`devnet`、`mainnet`、または `mesa`
`ARCHIVE_DB_HOST`	`localhost`	アーカイブ PostgreSQL ホスト
`ARCHIVE_DB_PORT`	`5432`	アーカイブ PostgreSQL ポート
`MINA_GRAPHQL_ENDPOINT`	`http://localhost:3085/graphql`	Mina デーモン GraphQL（チュートリアルモード）
`ARCHIVE_API_ENDPOINT`	`http://localhost:8282`	Archive-Node-API GraphQL（チュートリアルモード）
`ACCOUNTS_MANAGER_ENDPOINT`	`http://localhost:8181`	テストアカウントマネージャー（チュートリアルモード）

MCP ツール

ツールの登録はモードを認識します。特定のモードでバックエンドのインフラを利用できないツールは、そもそも登録されません（そのため、tools/list に表示されず、LLM がそれらについて推論することもありません）。

スナップショットモード（スキーマエクスプローラー）

ツール	説明
`query_archive_sql`	ローカルのアーカイブ Postgres に対して読み取り専用の SQL を実行します
`get_archive_schema`	アーカイブ DB のテーブル／カラムのメタデータを調べます
`get_sync_status`	DB の接続確認と基本的なアーカイブ統計を取得します
`list_examples` / `get_example`	定型 SQL ワークフロー（例：`custom_sql`）を見つけます

チュートリアルモード（ライブ lightnet — スナップショットの機能を包含）

すべてのスナップショットモードのツールに加えて、以下を利用できます。

ツール	説明
`get_account` / `get_block`	デーモンからライブの状態を取得し、利用できない場合はアーカイブ DB にフォールバックします
`get_staking_ledger` / `list_blocks` / `get_transaction` / `search_transactions`	アーカイブ DB の読み取り
`get_archive_stats`	アーカイブ内のブロック／コマンド／アカウントの集計
`get_best_chain` / `get_mempool` / `get_transaction_status`	デーモンへのライブクエリ
`get_genesis_constants` / `get_network_id` / `get_tracked_accounts`	デーモンのメタデータ
`get_events` / `get_actions` / `get_archive_blocks` / `get_network_state`	Archive-Node-API
`faucet` / `return_account` / `reset_session`	あらかじめ資金が用意されたテストアカウントプール（各 1550 MINA）
`send_payment` / `send_delegation`	デーモン署名済みトランザクション
`freeze_reset` / `unfreeze_reset` / `freeze_status`	人によるデモ用に定期的なチェーンリセットを一時停止します
`describe_state`	チェーン、メンプール、アカウント、リセット状態のワンショットスナップショット

ライブモード（パブリック Mina ネットワーク — 読み取り専用）

ツール	説明
`get_account` / `get_block` / `get_best_chain` / `get_mempool` / `get_transaction_status`	デーモンへのライブクエリ
`get_sync_status` / `get_genesis_constants` / `get_network_id`	デーモンのメタデータ
`get_events` / `get_actions` / `get_archive_blocks` / `get_network_state`	Archive-Node-API
`rosetta_status` / `rosetta_account` / `rosetta_block` / `rosetta_mempool` / `rosetta_mempool_transaction`	Mina-Rosetta Data API（Coinbase 仕様）
`describe_state`	プリフライト、Rosetta、Faucet のヒントを含むライブスナップショット
`list_examples` / `get_example`	ライブモードで利用できるワークフロー

開発

ビルド

npm run build          # compile TypeScript
npm run dev            # compile in watch mode

テストの実行

# All unit + MCP tests (no infrastructure needed)
npm run test:unit
npm run test:mcp

# All tests (unit + MCP)
npm test

# Watch mode
npm run test:watch

# Integration tests (requires running lightnet)
docker compose -f docker-compose.tutorial.yml up -d
npm run test:integration

テストの構成

test/
  unit/                    # Unit tests - mock all external dependencies
    accounts-manager.test.ts
    archive-db.test.ts
    example-library.test.ts
    live-provider.test.ts
    networks.test.ts
    reset-controller.test.ts
    schemas.test.ts
    session-tracker.test.ts
    shape.test.ts
    snapshot-provider.test.ts
    tutorial-provider.test.ts
    wallet-caps.test.ts
    wallets-loader.test.ts
  mcp/                     # MCP protocol tests - InMemoryTransport + Client
    helpers.ts             # Shared setup: mock providers, transport wiring
    snapshot.test.ts       # Snapshot mode
    tutorial.test.ts       # Tutorial mode: live tools, zkApp, faucet
    live.test.ts           # Live mode: read-only against public networks
    live-write.test.ts     # Live-write mode: wallet loading + signed sends
    http-transport.test.ts # HTTP transport: rate-limiting, /health, /metrics
    wallets-redaction.test.ts # Sweep: no private key leaks any tool response
  integration/             # Integration tests - require live lightnet
    lightnet.test.ts
    tutorial.test.ts

MCP テストでは、@modelcontextprotocol/sdk の InMemoryTransport を使って、プロセス内にリンクされたクライアントとサーバーのペアを作成します。これにより、ネットワークやデータベースを必要とせず、MCP プロトコル層全体（ツールの登録、スキーマの検証、リクエスト／レスポンス）をテストできます。

プロジェクト構成

src/
  index.ts                 # Entry point — CLI args, mode wiring, transport
  server-factory.ts        # Centralized tool registration per mode
  db/archive.ts            # PostgreSQL archive database client
  graphql/
    client.ts              # createMinaClient factory (wraps @o1-labs/mina-sdk MinaClient)
    accounts-manager.ts    # Tutorial-mode test accounts REST API client
  providers/
    snapshot.ts            # Read-only provider (archive DB only; no daemon)
    tutorial.ts            # Tutorial provider (daemon + archive + accounts mgr)
    live.ts                # Live provider (public network daemon, read-only)
    live-write.ts          # Live-write provider (wallet-backed signed sends)
  tools/
    accounts.ts            # Account tools (get_account, get_staking_ledger)
    blocks.ts              # Block tools (get_block, list_blocks, get_best_chain)
    transactions.ts        # Transaction tools (send_payment, search, mempool, status)
    network.ts             # Network tools (sync status, genesis, archive stats)
    schema.ts              # Archive SQL (query_archive_sql, get_archive_schema)
    zkapps.ts              # Archive-Node-API tools (events, actions, blocks)
    test-accounts.ts       # Faucet tools (acquire/release tutorial accounts)
    state.ts               # describe_state aggregator
    admin.ts               # Reset controls (freeze/unfreeze)
    rosetta.ts             # Rosetta Data API tools (live mode)
    wallets.ts             # list_wallets (live-write mode)
    examples.ts            # Cookbook tools (list_examples, get_example)
    shape.ts               # Response shapers (lite / transactions / full)
  transports/
    http.ts                # HTTP transport (Streamable + rate limiting + /metrics)
  wallets/
    loader.ts              # Wallet config + key file loader (live-write mode)
    types.ts               # WalletRegistry / LoadedWallet types
  session/tracker.ts       # Per-MCP-session account tracking (auto-release)
  reset/controller.ts      # Reset-window controller (freeze/unfreeze chain resets)
  snapshots/capture.ts     # CLI: capture archive DB snapshot
  examples/library.ts      # Cookbook workflow library (drives examples tools)
  networks.ts              # Public network configs (devnet/mainnet/mesa)

デーモンの GraphQL アクセスには、@o1-labs/mina-sdk の MinaClient を使用します。型付きメソッド（getAccount、getBestChain、getBlock、sendPayment、…）が、クエリ文字列、レスポンス形式、リトライ／タイムアウトのポリシーを管理します。mcp-server は意図的に薄いアダプターとして設計されており、SDK の上にチュートリアルモードのテストアカウントのオーケストレーションと MCP ツール登録層を追加します。

チュートリアルモードのサービス

docker-compose.tutorial.yml を使ってチュートリアルモードで実行すると、以下のサービスを利用できます。

サービス	URL	説明
Mina Daemon	`http://localhost:3085/graphql`	デーモンの GraphQL に直接接続します
NGINX Proxy	`http://localhost:8080/graphql`	CORS 対応のデーモン GraphQL
Explorer UI	`http://localhost:8080/`	軽量ブロックエクスプローラー
Accounts Manager	`http://localhost:8181/`	テストアカウント REST API
Archive-Node-API	`http://localhost:8282/`	アーカイブ GraphQL（イベント／アクション）
PostgreSQL	`localhost:5432`	アーカイブデータベース

チュートリアルモード／スナップショットモードでの使用

クライアント設定は、MCP クライアントの接続に記載されている { command, args } と同じです。--mode を tutorial または snapshot に変更し（--network は削除します）。異なるのはインフラストラクチャです。これらのモードはローカルサービスと通信するため、先にサービスを起動してください（前提条件とクイックスタートを参照）。

MCP サーバーがインフラストラクチャを起動することはありません。 Postgres／daemon／archive-node-api／accounts-manager に接続できない場合、ツールは接続エラーを返します。これは想定どおりの動作であり、バグではありません。

Fly.io へのデプロイ

このリポジトリには、MCP サーバーと lightnet イメージを単一の Fly マシンにまとめる Dockerfile と fly.toml が含まれています。MCP サーバーは Fly の TLS ターミネーターの背後で HTTP/SSE モードで動作します。lightnet の Explorer UI と GraphQL プレイグラウンドは、人間向けに 2 つ目のポートで公開されます。

# First-time setup (creates the app and provisions a machine)
flyctl launch --no-deploy --copy-config

# Or, if app already exists:
flyctl deploy

デプロイ後：

URL	対象	内容
`https://mina-mcp-sandbox.fly.dev/mcp`	AI クライアント	MCP streamable-HTTP エンドポイント
`https://mina-mcp-sandbox.fly.dev/health`	運用担当者	稼働確認プローブ＋アクティブなセッション数
`https://mina-mcp-sandbox.fly.dev:8080/`	人間	軽量版 Mina Explorer UI
`https://mina-mcp-sandbox.fly.dev:8080/graphql`	人間	GraphQL プレイグラウンド（CORS 対応の NGINX プロキシ）

flyctl apps rename でアプリを独自のサブドメインに変更するか、flyctl certs add mcp.your-domain.com でカスタムドメインを追加します（ドメインの CNAME を mina-mcp-sandbox.fly.dev に設定します）。

ホストされたサーバーへの MCP クライアントの接続

Claude Desktop／Claude Code の設定（.mcp.json）：

{
  "mcpServers": {
    "mina": {
      "url": "https://mina-mcp-sandbox.fly.dev/mcp"
    }
  }
}

最初のセッション呼び出しでは Mcp-Session-Id ヘッダーが返されます。クライアントは以降のすべてのリクエストで、このヘッダーを返す必要があります。セッションが切断されると、faucet を通じて取得したテストアカウントはすべて自動的に解放されます。

運用上の注意事項

auto_stop_machines = "stop" と min_machines_running = 0 により、アイドル時にマシンをゼロ台までスケールできます。アイドル状態の後の最初のリクエストでは、lightnet の同期中に約 60～120 秒のコールドスタートが発生します。
チェーンリセットのジャニター（計画中）は provider.resetController.isFrozen() を読み取ります。管理者やデモのプレゼンターは、freeze_reset MCP ツールで一時停止できます。
コンテナ内の起動順序については、deploy/start.sh を参照してください。lightnet が先に起動し、MCP サーバーが最後に起動します。

ロードマップ

GitHub の issueで管理しています。主な項目：

同梱 SQLite スナップショット（#28）— パッケージに SQLite アーカイブのスナップショットを同梱し、npx @o1-labs/mina-mcp-server --mode snapshot をインフラストラクチャなしで実行できるようにします。これは、ライブモードですでに実現しているセットアップ不要の使い方と同様です。
Rosetta Construction API — オフライン署名のフロー（derive → preprocess → metadata → payloads → sign → combine → submit）。読み取り専用の Rosetta Data API ツールはすでに提供されています。

最近追加されたもの：パブリックネットワーク（devnet／mainnet／mesa）に対するライブモード、ホスト型の Fly.io サンドボックス、ライブ書き込みモード（プロセス内署名）、公開済みの @o1-labs/mina-* SDK をトランスポート層として採用。チュートリアルモードは、設計上、引き続きインフラストラクチャ（ローカル lightnet）に依存します。これは、制御可能なネットワークを使った開発向けです。

コントリビュート

開発環境のセットアップ、テスト、プルリクエストの規約については、CONTRIBUTING.md を参照してください。脆弱性を発見した場合は、SECURITY.md を参照してください。

ライセンス

Apache-2.0

Markdown 対応

ログインしてコメント

基本情報

作者: MinaProtocol
言語: node
バージョン: 0.7.3
トランスポート: stdio
掲載日: 2026年5月31日
最終更新: 22 週間前
公式 Registry: io.github.MinaProtocol/mina-mcp-server

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

mina-mcp-server

mina-mcp-server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

mina-mcp-server

機能

どのモードを使えばよいですか？

MCP クライアントを接続する

動作を確認する

設定

トラブルシューティング

前提条件

クイックスタート

公開 Mina ネットワークに対する Live モード

Rosetta Data API（ライブモード）

Mesa ハードフォークのアップグレード追跡（mesa-mut）

ライブ書き込みモード（実験的 — クライアント側署名）

他のパブリックネットワークでのスナップショットモード

デモ：チュートリアルモードでのエンドツーエンド決済

インフラ設定（チュートリアル／スナップショット）

MCP ツール

スナップショットモード（スキーマエクスプローラー）

チュートリアルモード（ライブ lightnet — スナップショットの機能を包含）

ライブモード（パブリック Mina ネットワーク — 読み取り専用）

開発

ビルド

テストの実行

テストの構成

プロジェクト構成

チュートリアルモードのサービス

チュートリアルモード／スナップショットモードでの使用

Fly.io へのデプロイ

ホストされたサーバーへの MCP クライアントの接続

運用上の注意事項

ロードマップ

コントリビュート

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

Mesa ハードフォークのアップグレード追跡（`mesa-mut`）