Mirrornode MCP Server

🚀 Testnet Mirror Node MCP Server

This repository contains a Model Context Protocol (MCP) server that interfaces with the Hedera Testnet Mirror Node API. The server uses FastMCP, a TypeScript framework for creating MCP servers. It leverages the Zod schema for input validation.

✨ Features

• Endpoint Integration: Automatically converts the Hedera Mirror Node API (defined in OpenAPI specification format) into MCP-compatible tools.
• Server-Sent Events (SSE) Support: Clients cannot use SSE connections through this MCP server.
• Schema Validation: Ensures that request parameters conform to the defined schema using Zod.

📋 Prerequisites

Before running the server, make sure you have installed the following:

• Bun or any other environment capable of directly running TypeScript.

📦 Installation

(1) Clone the repository

git clone https://github.com/hedera-dev/mirrornode-mcp-server

(2) Navigate to the project directory

cd mirrornode-mcp-server

(3) Install dependencies

npm install

💻 Usage Examples

Basic Usage

To start the MCP server:

bun mcpServer.ts

After successful startup, you should see:

MCP server has started

The server will be accessible via the configured SSE endpoint. http://localhost:3333/hedera-testnet-mirror-node-api/sse

📚 Documentation

Project Structure

• mcpServer.ts: The entry file that initializes and starts the MCP server.
• openApiZod.ts: Contains the Mirror Node API endpoint definitions and an API client using zodios (an enhanced version similar to axios).
  • Note that this file is automatically generated by openapi-zod-client with some manual modifications.

How It Works

API Client Creation

Use the createApiClient function to create an API client for the Hedera Testnet Mirror Node. The MCP server acts as a proxy between this HTTP API client and its own SSE transport.

Endpoint Conversion

Process each endpoint definition from endpointDefinitions using the convertZodiosToMcp function:

• Validate that the endpoint uses the GET method.
• Map parameters to the Zod schema.
• Define an execution function to make the corresponding API call and return the result.
• Register the tool on the MCP server.

Server Initialization

Start the MCP server using the SSE transport.

🔧 Technical Details

Dependencies

• FastMCP: A framework for building MCP servers.
• Zod: A TypeScript-first schema declaration and validation library.
• openapi-zod-client: Generates Zodios code from OpenAPI specification files.

Author

Brendan Graetz

📄 License

MIT