https://github.com/hedera-dev/mirrornode-mcp-server
Hedera MCP server
https://github.com/hedera-dev/mirrornode-mcp-server
Last synced: 2 months ago
JSON representation
Hedera MCP server
- Host: GitHub
- URL: https://github.com/hedera-dev/mirrornode-mcp-server
- Owner: hedera-dev
- Created: 2025-03-25T11:18:39.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-08T07:49:34.000Z (6 months ago)
- Last Synced: 2025-04-08T08:42:31.996Z (6 months ago)
- Language: TypeScript
- Size: 13.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hedera 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 is built using [FastMCP](https://www.npmjs.com/package/fastmcp), a TypeScript framework for creating MCP servers.
It utilises [Zod](https://zod.dev/) schemas 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 connect to this MCP server over the SSE transport.
- **Schema Validation**: Ensures request parameters adhere to defined schemas using Zod.
## Prerequisites
Before running the server, ensure you have the following installed:
- [Bun](https://bun.sh/), or any other environment capable of running Typescript directly.
## Installation
(1) Clone the repository
```bash
git clone https://github.com/hedera-dev/mirrornode-mcp-server
```
(2) Navigate to the project directory
```bash
cd mirrornode-mcp-server
```
(3) Install dependencies
```bash
npm install
```
## Usage
To start the MCP server:
```bash
bun mcpServer.ts
```
Upon successful startup, you should see:
```
MCP server started
```
The server will be accessible via the configured SSE endpoint.
`http://localhost:3333/hedera-testnet-mirror-node-api/sse`
## Project Structure
- `mcpServer.ts`: The entry point that initializes and starts the MCP server.
- `openApiZod.ts`: Contains Mirror Node API endpoint definitions and an API client using `zodios` (like `axios` augmented with `zod` schema definitions).
- Note that this file has been programmatically generated using `openapi-zod-client` plus some manual modifications.
## How It Works
(1) API Client Creation
An API client is created for the Hedera Testnet Mirror Node using the `createApiClient` function.
The MCP server proxies between this HTTP API client and its own SSE transport.
(2) Endpoint Conversion:
Each endpoint definition from `endpointDefinitions` is processed by the `convertZodiosToMcp` function, which:
- Validates that the endpoint uses the `GET` method.
- Maps parameters to Zod schemas.
- Defines an execution function that makes the corresponding API call and returns the result.
- Registers the tool with the MCP server.
(3) Server Initialization:
The MCP server is started with SSE transport.
## Dependencies
- [FastMCP](https://www.npmjs.com/package/fastmcp): Framework for building MCP servers.
- [Zod](https://zod.dev/): TypeScript-first schema declaration and validation library.
- [openapi-zod-client](https://github.com/astahmer/openapi-zod-client): Generates Zodios code from an OpenAPI specification file.
## Author
[Brendan Graetz](https://blog.bguiz.com/)
## Licence
MIT