Mina Mcp Server

mina-mcp-server

[](https://www.npmjs.com/package/@o1-labs/mina-mcp-server) [](LICENSE) [](https://modelcontextprotocol.io)

MCP (Model Context Protocol) server for the Mina Protocol blockchain. Exposes Mina blockchain data and operations through MCP-compatible tools that can be used by AI assistants and other MCP clients.

New here? Jump to [Which mode do I want?](#which-mode-do-i-want) → [Connect your MCP client](#connect-your-mcp-client) → [Verify it works](#verify-it-works). For copy-paste prompts, see the [prompt cookbook](docs/examples.md).

> Status: beta / preview. Live mode talks to public Mina networks (devnet / mainnet / mesa) and needs no local infrastructure — run npx @o1-labs/mina-mcp-server --mode live --network devnet, or point your client at the [hosted sandbox](#deploying-on-flyio). Snapshot and tutorial modes are thin MCP layers over backing services (PostgreSQL, and for tutorial a local Mina lightnet) that you must stand up yourself first — see [Prerequisites](#prerequisites). A bundled SQLite snapshot for zero-infra snapshot mode is planned (#28).

Features

• 40+ MCP tools for querying accounts, blocks, transactions, zkApp events/actions, network/sync status, Rosetta, and archive SQL.
• Three operating modes:
• Live — read-only proxy to a public Mina network (devnet/mainnet/mesa). No local infra — the zero-setup default.
• Tutorial — full read/write against a local Mina lightnet (daemon, archive, test-account faucet).
• Snapshot — schema-only SQL access (query_archive_sql, get_archive_schema) against a frozen archive Postgres dump.
• Standardized Rosetta Data API tools (live mode) alongside the native GraphQL ones.
• Safe SQL access — read-only queries against the archive DB with timeout protection.
• Test-account faucet — acquire/release pre-funded accounts (tutorial mode).
• [Prompt cookbook](docs/examples.md) — copy-paste prompts that drive end-to-end tool sequences.

Which mode do I want?

| You want to… | Mode | Infra needed | |---|---|---| | Query a public network (balances, blocks, zkApp events, Rosetta) | live | None — just npx. Start here. | | Send transactions on a public network with your own keys | live + --wallets | None (keys signed in-process) | | Develop against a controllable chain (faucet, reset, write) | tutorial | Local Mina lightnet ([Prerequisites](#prerequisites)) | | Run analytics SQL over a historical archive dump | snapshot | A Postgres archive dump ([Prerequisites](#prerequisites)) |

Most people want live — it needs nothing installed beyond Node.

Connect your MCP client

Local (recommended), via npx — no clone, no infra:

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

Swap devnet for mainnet or mesa. For other modes, change --mode (and drop --network); see [Configuration](#configuration).

Hosted sandbox (zero install) — point your client at the URL:

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

The hosted sandbox runs tutorial mode against a shared lightnet (best-effort, no SLA). Use local live mode for real networks.

Where the config lives, per client:

| Client | Config | Notes | |---|---|---| | Claude Desktop | claude_desktop_config.json (Settings → Developer) | command/args shape above | | Claude Code | .mcp.json in the project, or claude mcp add | same shape | | Cursor | ~/.cursor/mcp.json (or Settings → MCP) | same shape | | Cline / Roo | the extension's MCP settings JSON | same shape | | Windsurf | ~/.codeium/windsurf/mcp_config.json | same shape | | Continue | ~/.continue/config.json under mcpServers | same shape | | Zed | settings.json under context_servers | Zed uses "command": { "path": "npx", "args": [...] } |

All clients except Zed take the same { command, args } object; only the file location differs. Hosted-URL configs work in any client that supports a remote/streamable-HTTP MCP server.

Verify it works

After wiring it up, ask your assistant:

> "Describe the current Mina network state."

It should call describe_state and return a snapshot with syncStatus (e.g. SYNCED), the network name, and mempool size. That's your green light. (On mesa, expect a PREFLIGHT caveat in the hints.)

Configuration

All flags have environment-variable equivalents; run npx @o1-labs/mina-mcp-server --help for the full surface.

$ mina-mcp-server --help
USAGE
  mina-mcp-server [--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)

| Flag | Env var | Values (default) | |---|---|---| | --mode | MINA_MCP_MODE | live / tutorial / snapshot (snapshot) | | --network | MINA_MCP_NETWORK | devnet / mainnet / mesa / mesa-mut (live only) | | --transport | MINA_MCP_TRANSPORT | stdio / http (stdio) | | --wallets | MINA_MCP_WALLETS | path to wallets.json (live-write) | | --allow-mainnet-writes | MINA_MCP_ALLOW_MAINNET_WRITES=1 | opt-in gate for mainnet sends | | (http only) | MINA_MCP_HTTP_PORT | port for --transport http (3000) | | --help, --version | — | print help / version and exit |

Troubleshooting

| Symptom | Fix | |---|---| | npx fails / "Unsupported engine" | Needs Node ≥ 20.18. Check node --version. | | Tools return "not reachable" in tutorial/snapshot | The server does not start infra — bring up the lightnet/Postgres first ([Prerequisites](#prerequisites)). | | Port already in use (tutorial lightnet) | Another lightnet/daemon is bound to 3085/8282/5432; stop it or remap ports. | | Changes not taking effect after editing source | Re-run npm run build (the client runs dist/, not src/). | | Hosted server: "Missing/!Unknown session id" | Your client must echo the Mcp-Session-Id header from initialize on every request — use a client that supports streamable-HTTP MCP. | | mesa data looks unstable | mesa is a preflight network — it can reset/rename without notice. Treat its data as ephemeral. |

Prerequisites

> Only needed for tutorial and snapshot modes. live mode needs none of this.

Common:

• Node.js >= 20.18
• Docker & Docker Compose (to run the backing services below)

Snapshot mode additionally requires:

| Component | Purpose | Default endpoint | |-----------|---------|------------------| | PostgreSQL with Mina archive schema + data | Source of all read queries | localhost:5432 |

You can bring this up with docker-compose.snapshot.yml (ships in the repo). A snapshot dump under ./snapshots/devnet-latest — or downloaded via the compose download profile — is required.

Tutorial mode additionally requires a full local lightnet:

| Component | Purpose | Default endpoint | |-----------|---------|------------------| | Mina Daemon GraphQL | Live chain queries, sending payments | http://localhost:3085/graphql | | Archive-Node-API | zkApp events/actions, archive blocks | http://localhost:8282 | | Accounts Manager | Test account faucet | http://localhost:8181 | | PostgreSQL (archive DB) | Read queries | localhost:5432 |

All four are brought up by docker-compose.tutorial.yml. Expect ~1–2 minutes for the network to sync before tools respond correctly.

> Note: if you install from npm (npx @o1-labs/mina-mcp-server), the docker-compose files are not included in the tarball — you will need to clone this repo, or copy the docker-compose.*.yml files out of it, to start the infra.

Quick Start

# 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

Live mode against a public Mina network

Live mode is a thin read-only proxy that turns MCP tool calls into GraphQL/HTTP requests against the o1Labs-hosted public endpoints. There is nothing to host — run it locally next to your MCP client:

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

Endpoints are best-effort services without SLAs and URLs are subject to change. Networks are classified by stability tier:

| Network | Stability | What it means | |---|---|---| | devnet | stable | Long-lived dev network. Expected to stick around. | | mainnet | stable | Production. Expected to stick around. | | mesa | preflight | Preview/staging network. May be reset, renamed, or retired without notice. Endpoints, archive-dump filenames, and even the network identity itself are not guaranteed stable. | | mesa-mut | preflight | Mesa Upgrade Test — a fork of mainnet state for rehearsing the Mesa hardfork. Tied to the upgrade rehearsal; will be reset/retired without notice. Genesis is a mainnet-state fork, but the daemon reports networkID mina:testnet (testnet signature schema). No Rosetta endpoint, no faucet, and no published archive dump (snapshot mode unavailable). |

When a LiveProvider is constructed against a preflight network, the server emits a [WARN] Network '' is a PREFLIGHT network… line at startup and prepends a PREFLIGHT hint to describe_state's hints[] — so any LLM consuming the output sees the caveat before reasoning about the data. If you build downstream automation against a preflight network, treat any data you gather as ephemeral and have a fallback to a stable network.

Rosetta Data API (live mode)

When a live-mode network has a Rosetta endpoint configured (devnet, mainnet, and mesa do today; mesa-mut does not), the server registers five Rosetta Data API tools alongside the daemon/archive ones. On a network without a Rosetta endpoint the rosetta_* tools are not registered at all, so the advertised tool list reflects what the network can actually do. These return responses in standardized Rosetta format — useful for LLMs and integrations that already speak Rosetta:

| Tool | Rosetta endpoint | Use | |---|---|---| | rosetta_status | POST /network/status | Current / genesis / oldest block, sync state | | rosetta_account | POST /account/balance | Balance for an address, optionally at a specific block | | rosetta_block | POST /block | Full block (with operations) by index or hash | | rosetta_mempool | POST /mempool | Pending transaction identifiers | | rosetta_mempool_transaction | POST /mempool/transaction | A single pending tx with operations |

Construction API (offline signing flow) is intentionally not included in this set; it's a follow-up with its own tool-shape design (macro-vs-literal).

Each network also carries optional pointers that the MCP server doesn't proxy itself but surfaces via describe_state.hints[] so an LLM can hand them to a human or a Rosetta-aware client:

| Network | Faucet | Rosetta | |---|---|---| | devnet | https://faucet.minaprotocol.com | https://devnet-rosetta.gcp.o1test.net | | mainnet | (none — exchanges only) | https://mainnet-rosetta.gcp.o1test.net | | mesa | https://faucet.minaprotocol.com | https://rosetta.mina-mesa-network.gcp.o1test.net | | mesa-mut | (none — mainnet-state fork) | (none) |

Mesa hardfork upgrade tracking (mesa-mut)

mesa-mut rehearses the Mesa hardfork upgrade. On --network mesa-mut the server registers an extra tool, get_upgrade_status, which joins the upgrade tracker (status.json) with the live daemon's current global slot to report the phase: current slot vs stopTransactionSlot / stopNetworkSlot, slots/minutes remaining, the Mesa genesis timestamp, and a transactionsOpen boolean with phase-aware hints[]. Check transactionsOpen before submitting a send — transactions sent after stopTransactionSlot are dropped.

For agent workflows, a companion Claude skill — [.claude/skills/mesa-upgrade](.claude/skills/mesa-upgrade/SKILL.md) — wraps this tool with a per-phase operator runbook (what to do / not do before, during, and after the fork).

Live write mode (experimental — client-side signing)

Live mode can be promoted from read-only to read+write by handing the server one or more wallet keys. Sends are signed in this process with mina-signer and submitted as pre-signed transactions to the daemon. No daemon-side wallet, no faucet on devnet/mainnet, no key material on the wire.

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

> EXPERIMENTAL — read this before pointing it at real value. > Wallet private keys are loaded unencrypted from disk into this process's memory. That's fine for ephemeral test wallets on devnet/mesa; it's not fine for production keys. Either: > - only load wallets containing money you can afford to lose, or > - don't use this mode for mainnet at all — use a hardware wallet or an offline signer for anything material. > > Pointing this at mainnet additionally requires --allow-mainnet-writes (or MINA_MCP_ALLOW_MAINNET_WRITES=1) as a deliberate speedbump against config typos.

wallets.json schema

{
  "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 files must contain exactly one EK… base58check private key (one line, no other content). Encrypted JSON key files are not supported in this revision.
• keyPath files must be chmod 600; the loader refuses to start otherwise.
• publicKey is verified at startup against the loaded key — catches "wrong key for this alias" mistakes before any tool runs.
• caps (optional, per wallet) bound a single transaction: maxFeeNanomina and maxAmountNanomina (decimal nanomina, 1 MINA = 1e9). A send exceeding a cap is refused before signing — a guardrail against a runaway/adversarial LLM draining a wallet. Memos are always capped at 32 bytes.
• defaultWallet is optional; if omitted, every send_payment/send_delegation call must pass from_alias or from.
• Paths may be relative to the config file's directory (so the whole bundle is portable).

Tool surface added in live-write mode (on top of the live-mode read tools):

| Tool | Descript

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MinaProtocol
• Source: MinaProtocol/mina-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.