Hedera Dev Mirrornode MCP Server

🚀 Hedera Testnet Mirror Node MCP Server

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

🚀 Quick Start

This repository houses a Model Context Protocol (MCP) server designed to interact with the Hedera Testnet Mirror Node API. It utilizes the FastMCP TypeScript framework for MCP server creation and employs the Zod schema for input validation.

✨ Features

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

📦 Installation

Prerequisites

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

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

Steps

(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 been started

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

📚 Documentation

Project Structure

• mcpServer.ts: The entry file for initializing and starting 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

(1) 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 the HTTP API client and its own SSE transport. (2) Endpoint Conversion Process each endpoint definition from endpointDefinitions using the convertZodiosToMcp function:

• Validate that the endpoint uses the GET method.
• Map the 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. (3) Server Initialization Start the MCP server with SSE transport.

🔧 Technical Details

This project relies on several key dependencies:

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

📄 License

This project is licensed under the MIT license.

Author

Brendan Graetz