mina

The Mina MCP server exposes tools to query and retrieve zkApp transaction data from the Mina blockchain via the Blockberry API. It implements the Model Context Protocol (MCP), allowing MCP-compatible clients to request detailed information about specific zkApp transactions or to fetch paginated lists of recent transactions. Tools include get-zkapp-transaction for one-off lookups by transaction hash and get-recent-zkapp-transactions for browsing recent activity with optional filtering by account and sorting options. The server formats results with details such as status, block height, fee payer/prover, account state changes, security warnings, balance changes, and timestamps, making it straightforward for AI models to integrate real-time blockchain data into conversations.

To use the server with a client like Claude Desktop, configure the MCP server endpoint in the client’s mcpServers section. The provided example shows how to run the server via npx and supply your Blockberry API key as an environment variable so the server can fetch data from Blockberry in real time. After setup, you can invoke the available tools by sending the corresponding MCP requests (e.g., get-zkapp-transaction with a txHash, or get-recent-zkapp-transactions with pagination and filters).

Prerequisites:

• Node.js (LTS version) and npm/yarn installed
• A Blockberry API key (sign up at https://blockberry.one)
• Basic familiarity with MCP clients (e.g., Claude Desktop)

Install and run:

1. Install Node.js if you don’t have it already

   • macOS/macOS with Homebrew: brew install node
   • Windows: download from nodejs.org and run the installer
   • Linux: use your distribution’s package manager, e.g., sudo apt install nodejs npm

2. Obtain a Blockberry API key from Blockberry and keep it ready

3. Start the Mina MCP server via npx (example shown below). This will download and run the mina-mcp-server package on demand and pass your API key to the server:

   npx -y mina-mcp-server

4. Ensure the server is reachable by your MCP client. The server will use the BLOCKBERRY_API_KEY environment variable to authenticate with Blockberry and fetch zkApp transaction data.

Optional: If you prefer a docker or other runtime, adapt the command accordingly, but the repository README demonstrates the npx approach for quick start.

Notes:

• Ensure BLOCKBERRY_API_KEY is kept secret and not committed to code or config files.
• The server supports pagination (page, size) and filtering by accountId for recent transactions, and sorting options (ASC/DESC, AGE).
• If you encounter API rate limits or authentication errors from Blockberry, verify your API key permissions and consider using a higher-tier key if available.
• When testing with Claude Desktop, ensure the client configuration’s mcpServers entry matches the server identifier used in your setup (for example, mina or mina-mcp).
• If running via npm script, make sure you’re using a recent Node.js version compatible with the mina-mcp-server package.