mina-mcp-server

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? → Connect your MCP client → Verify it works. For copy-paste prompts, see the prompt cookbook.

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. 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. 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 — copy-paste prompts that drive end-to-end tool sequences.

Which mode do I want?

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.

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:

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 <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)

Troubleshooting

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:

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:

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:

When a LiveProvider is constructed against a preflight network, the server emits a [WARN] Network '<name>' 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:

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:

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 — 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):

describe_state in live-write mode adds a wallets[] block (aliases, publicKeys, balances — never keys) and prepends a Live-WRITE mode… hint, so an LLM picks up the new capabilities on the first orient.

Safety guarantees (enforced, not just documented):

• Permission gate. Any key file with mode wider than 0600 fails startup loudly.
• Mainnet writes opt-in. --allow-mainnet-writes is a hard requirement for --network mainnet --wallets ….
• Nonce cache. max(daemon_nonce, last_submitted+1) — survives archive-lag races without burning a nonce on failed submits.
• Dry-run. send_payment(dry_run: true) returns the signed payload + computed hash without hitting the daemon.
• Automated redaction sweep. test/mcp/wallets-redaction.test.ts fires every registered tool with bogus args and asserts the server's loaded private key never appears in any response.

Snapshot mode against other public networks

The --profile download path of docker-compose.snapshot.yml fetches dumps from the public bucket https://storage.googleapis.com/mina-archive-dumps. The URL layout is <prefix>-<YYYY-MM-DD>_<HOUR>.sql.tar.gz. To target a different network, override ARCHIVE_DUMP_PREFIX:

# 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 is a preflight network. The dump prefix above is internal ops naming and is not a stable convention — it may change or stop being published without notice when mesa graduates or is retired. Treat snapshot data from mesa as ephemeral.

In live mode the server hides every tool that would need infra it doesn't have:

• no archive Postgres → no query_archive_sql, get_archive_schema, list_blocks, search_transactions, get_transaction, get_staking_ledger, get_archive_stats;
• no accounts-manager / faucet → no faucet, return_account, reset_session;
• no reset janitor → no freeze_reset, unfreeze_reset, freeze_status;
• public daemons don't sign for you → no send_payment, send_delegation, get_tracked_accounts.

get_block requires a stateHash in live mode — use get_archive_blocks (Archive-Node-API) to discover one first.

Demo: end-to-end payment in tutorial mode

The point of running this server is that a single natural-language prompt can drive a multi-step on-chain flow that would otherwise need half a dozen separate GraphQL calls. Once the lightnet is up and your MCP client is connected, this prompt:

Grab two funded test accounts from the faucet. Send 10 MINA from the first to the second, then poll until it lands in a block — show me the mempool state right after submission and the block height it gets included in. Once confirmed, check both balances and return both accounts.

drives the following tool sequence (excerpted from a real tutorial-mode run):

End-to-end wall-clock was a few seconds on a synced lightnet. The flow exercises every tutorial-only tool family in one go — faucet/return, payment submission, mempool, status polling, block/account lookup — making it a useful smoke check after deploy.

Infrastructure configuration (tutorial / snapshot)

These configure where the backing services live; live mode doesn't use them. Copy .env.example to .env and adjust as needed:

cp .env.example .env

Key variables:

MCP Tools

Tool registration is mode-aware — tools whose backing infra isn't available in a given mode aren't registered at all (so they don't show up in tools/list, and an LLM never reasons about them).

Snapshot mode (schema explorer)

Tutorial mode (live lightnet — superset of snapshot)

All snapshot tools, plus:

Live mode (public Mina network — read-only)

Development

Build

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

Running Tests

# 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 Structure

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

The MCP tests use @modelcontextprotocol/sdk's InMemoryTransport to create a linked client-server pair in-process. This tests the full MCP protocol layer (tool registration, schema validation, request/response) without needing any network or database.

Project Structure

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)

Daemon GraphQL access goes through @o1-labs/mina-sdk's MinaClient — typed methods (getAccount, getBestChain, getBlock, sendPayment, …) own the query strings, response shapes, and retry/timeout policy. mcp-server is deliberately a thin adapter: it adds tutorial-mode test-account orchestration and the MCP tool registration layer on top of the SDK.

Tutorial Mode Services

When running in tutorial mode with docker-compose.tutorial.yml, the following services are available:

Using with tutorial / snapshot mode

Client config is the same { command, args } shown in Connect your MCP client — just change --mode to tutorial or snapshot (and drop --network). The difference is the infrastructure: these modes talk to local services, so bring those up first (see Prerequisites and Quick Start).

The MCP server will not start the infrastructure for you. If Postgres / daemon / archive-node-api / accounts-manager are not reachable, tools return connection errors — that's expected, not a bug.

Deploying on Fly.io

The repo ships a Dockerfile and fly.toml that bundle the MCP server with the lightnet image into a single Fly machine. The MCP server runs in HTTP/SSE mode behind Fly's TLS terminator; the lightnet's Explorer UI + GraphQL playground are exposed on a second port for humans.

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

# Or, if app already exists:
flyctl deploy

After deploy:

Rename the app to your own subdomain with flyctl apps rename or attach a custom domain via flyctl certs add mcp.your-domain.com (CNAME the domain to mina-mcp-sandbox.fly.dev).

Connecting an MCP client to the hosted server

Claude Desktop / Claude Code config (.mcp.json):

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

The first session call returns a Mcp-Session-Id header that the client must echo on every subsequent request. When the session disconnects, every test account it acquired via faucet is automatically released.

Operational notes

• auto_stop_machines = "stop" + min_machines_running = 0 lets the machine scale to zero when idle. First request after idle pays a ~60–120s cold-start while the lightnet syncs.
• The chain-reset janitor (planned) reads provider.resetController.isFrozen(); admins / demo presenters can pause it via the freeze_reset MCP tool.
• See deploy/start.sh for the in-container boot order: lightnet first, MCP server last.

Roadmap

Tracked in GitHub issues. Highlights:

• Bundled SQLite snapshot (#28) — ship a SQLite archive snapshot inside the package so npx @o1-labs/mina-mcp-server --mode snapshot runs with zero infra, the same zero-setup story live mode already has.
• Rosetta Construction API — the offline signing flow (derive → preprocess → metadata → payloads → sign → combine → submit). The read-only Rosetta Data API tools already ship today.

Shipped recently: live mode against public networks (devnet / mainnet / mesa), a hosted Fly.io sandbox, live-write mode (in-process signing), and adoption of the published @o1-labs/mina-* SDKs as the transport layer. Tutorial mode stays infrastructure-dependent (local lightnet) by design — it's for development against a controllable network.

Contributing

See CONTRIBUTING.md for dev setup, testing, and PR conventions. Found a vulnerability? See SECURITY.md.

License

Apache-2.0