Hedera MCP Server

What is Hedera MCP Server?

A production-ready Model Context Protocol (MCP) server that enables AI agents and LLMs to interact with the Hedera hashgraph network through natural language. It executes transactions, checks balances, and manages tokens—allowing users to describe operations in plain English. Designed for developers building AI-powered Hedera applications.

How to use Hedera MCP Server?

Run via Docker (npm run docker:dev:full) or local development (pnpm install && pnpm run dev:full) after configuring a .env file with Hedera and OpenAI credentials. Connect an MCP client to the server’s SSE endpoint (http://localhost:3000/stream) or JSON-RPC endpoint (http://localhost:3000/). Tools are invoked through MCP calls.

Key features of Hedera MCP Server

• Natural language transaction and query execution
• Token and smart contract operations
• Scheduled transactions with natural language
• Credit system with HBAR payments
• API key authentication via Hedera signature verification
• Admin web portal for credit and user management

Use cases of Hedera MCP Server

• Transfer HBAR or tokens using conversational commands
• Create, mint, or transfer fungible and non-fungible tokens
• Deploy and interact with smart contracts naturally
• Schedule future transactions without manual coding
• Query account balances, transaction history, and token info via text

FAQ from Hedera MCP Server

What do I need to run the server?

You must have a Hedera account (testnet or mainnet), a Hedera private key, and an OpenAI API key. The server is built with Node.js and pnpm; Docker is recommended for zero-config startup.

How does authentication work?

Authentication is enabled by default (REQUIRE_AUTH=true). Users request a challenge via the request_auth_challenge MCP tool, sign the challenge with their Hedera private key, and call verify_auth_signature to receive an API key. The key is used in the Authorization: Bearer header for subsequent requests.

What transport protocols are supported?

The server supports Server-Sent Events (SSE) at /stream and JSON-RPC via HTTP POST at /. A stdio transport is also available for integration with Claude Desktop.

How does the credit system work?

Operations consume credits that must be purchased with HBAR. Users call the purchase_credits tool to initiate a transaction, then verify_payment to allocate credits. Natural language tools (e.g., execute_transaction) require credits and use OpenAI.

Does the server support mainnet or testnet?

The default network is testnet, but it can be changed to mainnet by setting HEDERA_NETWORK=mainnet in the .env file.