Hedera Testnet Mirror Node MCP server

The Hedera Testnet Mirror Node MCP server provides an interface to the Hedera Testnet Mirror Node API following the Model Context Protocol (MCP). Built with FastMCP and Zod validation, it converts Mirror Node API endpoints into MCP-compatible tools that clients can access.

Prerequisites

Before running the server, ensure you have the following installed:

• Bun or another environment capable of running TypeScript directly

Installation

Follow these steps to install the MCP server:

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

Running the Server

Start the MCP server with the following command:

bun mcpServer.ts

Upon successful startup, you should see:

MCP server started

The server will be accessible via the SSE endpoint at:

http://localhost:3333/hedera-testnet-mirror-node-api/sse

How It Works

API Client Creation

The server creates an API client for the Hedera Testnet Mirror Node using the createApiClient function. This MCP server acts as a proxy between the HTTP API client and its own SSE transport.

Endpoint Conversion

The server converts each endpoint definition into an MCP-compatible tool by:

• Validating that the endpoint uses the GET method
• Mapping parameters to Zod schemas for validation
• Defining execution functions that make API calls and return results
• Registering each tool with the MCP server

Server Initialization

The MCP server is started with SSE transport enabled, allowing clients to connect and use the exposed API tools.

Key Features

• Automatic API Conversion: Transforms Hedera Mirror Node APIs defined in OpenAPI specification into MCP-compatible tools
• Server-Sent Events Support: Provides an SSE transport for client connections
• Schema Validation: Uses Zod to ensure request parameters meet defined specifications

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hedera-testnet-mirror-node-api" '{"command":"bun","args":["mcpServer.ts"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "hedera-testnet-mirror-node-api": {
            "command": "bun",
            "args": [
                "mcpServer.ts"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "hedera-testnet-mirror-node-api": {
            "command": "bun",
            "args": [
                "mcpServer.ts"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect