mina-mcp-server

Name: mina-mcp-server
Author: MinaProtocol

本地服务

github.com/MinaProtocol金融数据022 周前更新

代码仓库

关于 mina-mcp-server

mina-mcp-server 通过 MCP 向 AI 助手及其他 MCP 客户端提供 Mina Protocol 的账户、区块、交易、zkApp、归档 SQL 和 Rosetta 数据。Live 模式无需本地基础设施即可读取公开网络；教程和快照模式分别用于本地链实验和归档分析。

主要功能

0140 多种区块链查询工具
02实时、教程和快照三种模式
03查询账户、区块、交易及 zkApp 数据
04提供 Rosetta Data API 查询
05对归档数据库执行只读 SQL
06教程模式提供测试账户水龙头

适用场景

01查询公开 Mina 网络的账户与区块
02分析 zkApp 事件和操作记录
03对历史归档数据运行 SQL 查询
04在本地 lightnet 上测试读写流程

MCP 相关

服务器通过 MCP 向客户端提供 Mina 网络数据和操作工具。Live 模式代理公开网络查询；教程模式支持本地 lightnet 的读写操作，快照模式提供归档 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）服务。通过兼容 MCP 的工具提供 Mina 区块链数据和操作，供 AI 助手及其他 MCP 客户端使用。

初次使用？ 请依次查看：我该选择哪种模式？ → 连接 MCP 客户端 → 验证是否正常运行。要查看可直接复制粘贴的提示词，请参阅提示词示例集。

状态：beta / 预览版。 实时模式连接公共 Mina 网络（devnet / mainnet / mesa），无需本地基础设施——运行 npx @o1-labs/mina-mcp-server --mode live --network devnet，或将客户端连接到托管沙盒。快照和教程模式是依赖后端服务（PostgreSQL；教程模式还需要本地 Mina lightnet）的轻量 MCP 层，你必须先自行搭建这些服务——请参阅先决条件。计划为零基础设施的快照模式提供捆绑的 SQLite 快照（#28）。

功能

40 多个 MCP 工具，用于查询账户、区块、交易、zkApp 事件/操作、网络/同步状态、Rosetta 和归档 SQL。
三种运行模式：
- 实时——公共 Mina 网络（devnet/mainnet/mesa）的只读代理。无需本地基础设施——默认零配置。
- 教程——通过本地 Mina lightnet（daemon、归档服务、测试账户水龙头）进行完整读写操作。
- 快照——针对冻结的归档 Postgres 转储提供仅限架构的 SQL 访问（query_archive_sql、get_archive_schema）。
标准化的 Rosetta Data API 工具（实时模式），以及原生 GraphQL 工具。
安全的 SQL 访问——对归档数据库执行只读查询，并提供超时保护。
测试账户水龙头——获取/释放预先注资的账户（教程模式）。
提示词示例集——可直接复制粘贴、用于执行端到端工具序列的提示词。

我该选择哪种模式？

你想要……	模式	所需基础设施
查询公共网络（余额、区块、zkApp 事件、Rosetta）	`live`	无——只需 `npx`。从这里开始。
使用自己的密钥在公共网络上发送交易	`live` + `--wallets`	无（密钥在进程内签名）
基于可控链进行开发（水龙头、重置、写入）	`tutorial`	本地 Mina lightnet（先决条件）
对历史归档转储运行分析 SQL	`snapshot`	Postgres 归档转储（先决条件）

大多数人应该选择 live——除 Node.js 外，无需安装任何东西。

连接 MCP 客户端

本地运行（推荐），通过 npx — 无需克隆或配置基础设施：

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

将 devnet 替换为 mainnet 或 mesa。如需使用其他模式，请更改 --mode（并移除 --network）；请参阅配置。

托管沙盒（无需安装）— 将客户端指向该 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	`~/.continue/config.json` 中的 `mcpServers`	格式相同
Zed	`settings.json` 中的 `context_servers`	Zed 使用 `"command": { "path": "npx", "args": [...] }`

除 Zed 外，所有客户端都使用相同的 { command, args } 对象；区别仅在于文件位置。支持远程/可流式传输 HTTP MCP 服务的客户端均可使用托管 URL 配置。

验证是否正常运行

完成配置后，向助手询问：

“描述当前 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` 的路径（live 写入模式）
`--allow-mainnet-writes`	`MINA_MCP_ALLOW_MAINNET_WRITES=1`	主网发送操作的选择加入开关
（仅限 http）	`MINA_MCP_HTTP_PORT`	`--transport http` 的端口（`3000`）
`--help`、`--version`	—	打印帮助信息/版本并退出

故障排除

症状	解决方法
`npx` 失败 / “Unsupported engine”	需要 Node ≥ 20.18。检查 `node --version`。
`tutorial`/`snapshot` 模式下工具返回“not reachable”	服务不会启动基础设施 — 请先启动 lightnet/Postgres（前提条件）。
端口已被占用（`tutorial` lightnet）	另一个 lightnet/daemon 正在使用 3085/8282/5432；请停止它或重新映射端口。
修改源代码后更改未生效	重新运行 `npm run build`（客户端运行的是 `dist/`，而不是 `src/`）。
托管服务：“Missing/!Unknown session id”	客户端必须在每个请求中回显 `initialize` 返回的 `Mcp-Session-Id` 标头 — 请使用支持可流式传输 HTTP MCP 的客户端。
`mesa` 数据看起来不稳定	`mesa` 是一个预检网络 — 可能会在不通知的情况下重置/更名。请将其数据视为临时数据。

前提条件

仅 tutorial 和 snapshot 模式需要。live 模式无需任何这些条件。

通用：

Node.js >= 20.18
Docker 和 Docker Compose（用于运行下方的后端服务）

snapshot 模式还需要：

组件	用途	默认端点
带有 Mina archive 架构和数据的 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（归档数据库）	读取查询	`localhost:5432`

这四项服务都由 docker-compose.tutorial.yml 启动。网络同步预计需要约 1–2 分钟，之后工具才能正确响应。

注意：如果从 npm 安装（npx @o1-labs/mina-mcp-server），tarball 中不包含 docker-compose 文件——你需要克隆此仓库，或从中复制 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 硬分叉。与升级演练绑定；将会在未通知的情况下重置或退役。创世状态是主网状态的分叉，但守护进程报告的 networkID 为 `mina:testnet`（测试网签名架构）。没有 Rosetta 端点、没有水龙头，也没有已发布的归档转储（无法使用 snapshot 模式）。

当针对预演网络构造 LiveProvider 时，服务会在启动时输出一行 [WARN] Network '<name>' is a PREFLIGHT network…，并在 describe_state 的 hints[] 前添加 PREFLIGHT 提示——因此，任何使用该输出的大模型都会在推理数据之前看到这一注意事项。如果你基于预演网络构建下游自动化，应将收集到的所有数据视为临时数据，并准备好稳定网络作为备用选项。

Rosetta Data API（实时模式）

当实时模式网络配置了 Rosetta 端点时（目前 devnet、mainnet 和 mesa 已配置，mesa-mut 未配置），服务会在守护进程／归档工具旁注册五个 Rosetta Data API 工具。对于没有 Rosetta 端点的网络，根本不会注册 rosetta_* 工具，因此公开的工具列表会准确反映该网络实际能执行的操作。这些工具会返回标准化的 Rosetta 格式响应，适用于已支持 Rosetta 的大模型和集成：

工具	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 服务不会自行代理这些指针，但会通过 describe_state.hints[] 提供，以便大模型转交给人工操作员或支持 Rosetta 的客户端：

网络	水龙头	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）与实时守护进程的当前全局 slot 数据合并，以报告当前阶段：当前 slot 与 stopTransactionSlot / stopNetworkSlot 的对比、剩余 slot／分钟数、Mesa 创世时间戳，以及包含阶段相关 hints[] 的 transactionsOpen 布尔值。提交发送操作前，请先检查 transactionsOpen——在 stopTransactionSlot 之后发送的交易会被丢弃。

对于 Agent 工作流，配套的 Claude 技能——.claude/skills/mesa-upgrade——会为该工具提供分阶段的操作手册（分叉前、期间和之后该做什么／不该做什么）。

实时写入模式（实验性 — 客户端签名）

为服务器提供一个或多个钱包密钥，即可将实时模式从只读升级为读写。发送操作会在此进程中使用 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 私钥（一行，不含其他内容）。此版本不支持加密的 JSON 密钥文件。
keyPath 文件的权限必须为 chmod 600；否则加载器会拒绝启动。
启动时会根据加载的密钥验证 publicKey，以便在任何工具运行前发现“此别名对应的密钥错误”问题。
caps（可选，每个钱包单独设置）用于限制单笔交易：maxFeeNanomina 和 maxAmountNanomina（十进制 nanomina，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 的密钥文件都会导致启动失败并明确报错。
主网写入需显式启用。 使用 --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`	每日两次，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；
没有 accounts-manager / faucet → 没有 faucet、return_account、reset_session；
没有重置清理程序 → 没有 freeze_reset、unfreeze_reset、freeze_status；
公共守护进程不会替你签名 → 没有 send_payment、send_delegation、get_tracked_accounts。

实时模式下，get_block 需要提供 stateHash——请先使用 get_archive_blocks（Archive-Node-API）查找一个。

演示：教程模式下的端到端支付

运行此服务的意义在于，只需一条自然语言提示词，就能驱动多步链上流程；否则，这个流程需要调用六七次独立的 GraphQL 接口。Lightnet 启动且 MCP 客户端连接后，使用以下提示词：

从 faucet 获取两个已注资的测试账户。从第一个账户向第二个账户发送 10 MINA，然后轮询，直到交易进入区块——请显示提交后立即的 mempool 状态，以及交易被纳入的区块高度。确认后，检查两个账户的余额并归还这两个账户。

这会驱动以下工具调用序列（摘自一次真实的教程模式运行）：

步骤	工具	关键输出
1	`faucet` ×2	两个账户，每个有 1550 MINA
2	`send_payment`（10 MINA，0.1 手续费）	交易哈希 `5JtVaGBj…6Tto`
3	按发送方筛选的 `get_mempool`	捕获待处理交易
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 上，整个流程只需几秒钟。它一次性运行了所有仅限教程模式的工具系列——faucet/归还、支付提交、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 中，大模型也不会考虑它们）。

Snapshot 模式（架构浏览器）

工具	描述
`query_archive_sql`	对本地归档 PostgreSQL 执行只读 SQL 查询
`get_archive_schema`	查看归档数据库的表和列元数据
`get_sync_status`	数据库连接探测 + 基本归档统计信息
`list_examples` / `get_example`	查找现成的 SQL 工作流（例如 `custom_sql`）

Tutorial 模式（实时轻量网络——包含 Snapshot 模式的全部工具）

所有 Snapshot 模式工具，另加：

工具	描述
`get_account` / `get_block`	从守护进程读取实时状态，归档数据库不可用时回退使用归档数据库
`get_staking_ledger` / `list_blocks` / `get_transaction` / `search_transactions`	从归档数据库读取数据
`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`	一次性获取链 + 内存池 + 账户 + 重置状态的快照

Live 模式（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 + 水龙头提示
`list_examples` / `get_example`	适用于 Live 模式的工作流

开发

构建

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 之上添加 Tutorial 模式测试账户编排和 MCP 工具注册层。

Tutorial 模式服务

在 Tutorial 模式下使用 docker-compose.tutorial.yml 运行时，可使用以下服务：

服务	URL	描述
Mina 守护进程	`http://localhost:3085/graphql`	直接访问守护进程 GraphQL
NGINX 代理	`http://localhost:8080/graphql`	支持 CORS 的守护进程 GraphQL
Explorer UI	`http://localhost:8080/`	轻量级区块浏览器
账户管理器	`http://localhost:8181/`	测试账户 REST API
Archive-Node-API	`http://localhost:8282/`	归档 GraphQL（事件/操作）
PostgreSQL	`localhost:5432`	归档数据库

使用 tutorial / snapshot 模式

客户端配置与连接 MCP 客户端中所示的 { command, args } 相同，只需将 --mode 改为 tutorial 或 snapshot（并移除 --network）。区别在于基础设施：这些模式会连接本地服务，因此请先启动这些服务（参见前置条件和快速开始）。

**MCP 服务不会替你启动基础设施。**如果无法连接 Postgres / daemon / archive-node-api / accounts-manager，工具会返回连接错误——这是预期行为，不是 bug。

在 Fly.io 上部署

仓库提供了 Dockerfile 和 fly.toml，将 MCP 服务与 lightnet 镜像打包到单个 Fly 虚拟机中。MCP 服务以 HTTP/SSE 模式运行在 Fly TLS 终止器之后；lightnet 的 Explorer UI 和 GraphQL playground 则通过第二个端口提供给用户访问。

# 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 playground（启用 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 issues 中。重点包括：

内置 SQLite 快照（#28）——在软件包中附带 SQLite 归档快照，使 npx @o1-labs/mina-mcp-server --mode snapshot 无需任何基础设施即可运行，实现与 live 模式相同的零配置体验。
Rosetta Construction API——离线签名流程（derive → preprocess → metadata → payloads → sign → combine → submit）。只读的 Rosetta Data API 工具目前已随产品提供。

近期已交付：支持连接公共网络（devnet / mainnet / mesa）的 live 模式、托管的 Fly.io 沙盒、live-write 模式（进程内签名），以及采用已发布的 @o1-labs/mina-* SDK 作为传输层。tutorial 模式按设计仍依赖基础设施（本地 lightnet）——它用于在可控网络上进行开发。

贡献

开发环境设置、测试和 PR 规范请参见 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 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

mina-mcp-server

关于 mina-mcp-server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

mina-mcp-server

功能

我该选择哪种模式？

连接 MCP 客户端

验证是否正常运行

配置

故障排除

前提条件

快速开始

针对公共 Mina 网络的 Live 模式

Rosetta Data API（实时模式）

Mesa 硬分叉升级跟踪（mesa-mut）

实时写入模式（实验性 — 客户端签名）

针对其他公共网络的快照模式

演示：教程模式下的端到端支付

基础设施配置（教程 / 快照）

MCP 工具

Snapshot 模式（架构浏览器）

Tutorial 模式（实时轻量网络——包含 Snapshot 模式的全部工具）

Live 模式（Mina 公共网络——只读）

开发

构建

运行测试

测试结构

项目结构

Tutorial 模式服务

使用 tutorial / snapshot 模式

在 Fly.io 上部署

将 MCP 客户端连接到托管服务

运维说明

路线图

贡献

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

Mesa 硬分叉升级跟踪（`mesa-mut`）