Mina MCP Server

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](docs/examples.md) — 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 ] [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 ' ' 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:

| rosetta_mempool | POST /mempool | Pending tran