hedera-mcp/hedera-mcp-server

Hedera MCP Server

The Hedera Model Context Protocol (MCP) server provides unified blockchain services for the Hedera Hashgraph network.
It enables AI Agents, AI Assistants and Developers to interact with Hedera seamlessly via a standardized MCP interface.

📋 Contents

• Overview
• Features
• Supported Networks
• Prerequisites
• Installation
• Server Configuration
• Usage
• API Reference
  • Tools
  • Resources
• Security Considerations
• Project Structure
• Development
• License

🔭 Overview

The Hedera MCP Server leverages the Model Context Protocol to provide comprehensive Hedera blockchain services to AI agents and apps.
It supports operations such as:

• Querying account balances and token holdings (HTS tokens, NFTs)
• Transferring native HBAR and HTS tokens
• Interacting with Hedera smart contracts (Solidity contracts on Hedera network)
• Retrieving transaction and record details
• Managing token information and metadata

All services are exposed through a unified MCP tool and resource interface, making it easy for AI agents to discover and use Hedera blockchain functionality.

✨ Features & Tools

This document outlines the comprehensive features and tools available for interacting with EVM, Hedera, and DOVU ecosystems.

🔗 Blockchain Network & Block Data

• Network Information: Get detailed information for any supported network, including both EVM (Chain ID, block number, RPC URL) and Hedera native (Mirror Node URL) data.
• Supported Networks: Retrieve a list of all supported EVM and Hedera networks.
• Block Exploration: Fetch blocks by their number or hash, and retrieve the latest block on the network.
• Timestamp Queries (Hedera): Find blocks within a specific timestamp range or by a precise consensus timestamp.

🪙 Account & Token Services

• Unified Balance Checks: Get native HBAR and token balances for any account using either its EVM address (0x...) or Hedera ID (0.0...).
• Comprehensive Portfolio: Retrieve a complete account portfolio, including HBAR balance, all fungible tokens (with their balances), and a list of all owned NFTs.
• Token Information: Get detailed metadata for any token, whether it's an ERC20, ERC721, or a native Hedera token (HTS).
• NFT Management:
  • Check the balance and ownership of specific NFTs.
  • Get detailed metadata and URI for ERC721 and ERC1155 tokens.
  • List all NFTs owned by an account, with options to filter by collection.
• Transfers:
  • HBAR: Send native HBAR between accounts.
  • HTS: Transfer native Hedera fungible tokens and NFTs.
  • ERC Standards: Transfer ERC20, ERC721, and ERC1155 tokens.
• Token Allowances: Approve other addresses to spend your ERC20 tokens.

🛠️ Address Utilities

• Address Conversion: Convert between Hedera account IDs and EVM addresses.
• Format Checking: Check if an address is in Hedera or EVM format.
• Address Derivation: Derive a public EVM address from a private key.

📝 Smart Contract Interactions

• Deployment:
  • Deploy new ERC20 (fungible) and ERC721 (NFT) contracts to a specified network.
• Verification:
  • Locally verify a deployed contract's parameters (name, symbol, supply, etc.) against the initial inputs.
  • Verify deployed ERC20 contracts on the Hashscan block explorer.
• Read & Write Operations:
  • Read data from any smart contract by calling its functions.
  • Execute contract functions to write data to the blockchain, with support for passing arguments and value.
• Contract Information:
  • Check if an address or ID belongs to a smart contract.
  • Get detailed information and execution results for Hedera native contracts.

📊 Blockchain Data Access & Transactions

• Transaction History: Get a list of transactions for an account with powerful filtering options (by type, result, timestamp, etc.).
• Activity Summary: Generate a summary of an account's recent activity, including transaction counts, success rates, and total fees.
• Transaction Details: Fetch a specific transaction by its hash (EVM) or ID (Hedera).
• Transaction Receipts: Retrieve detailed transaction receipts, which include logs and event data.
• Gas Estimation: Estimate the gas cost for an EVM transaction before sending it.

📈 DeFi & Exchange Data (via DexScreener)

• Pair & Token Search: Search for token pairs by name, symbol, or address.
• Market Data: Get information on token pairs, including price, volume, and liquidity.
• Advanced Queries: Perform advanced searches for tokens, get data for top boosted or recently updated tokens, and view trading activity on a specific chain.
• Multi-Chain Data: Aggregate token pair information across multiple blockchains.

🌍 DOVU OS Integration

• Workflow Management:
  • List, filter, and get details for all DOVU workflows and their instances.
  • Publish new workflows and workflow instances.
• Actor & User Management:
  • Register new actors (e.g., suppliers, verifiers) in the DOVU system.
  • Log in to get an authentication token.
  • Assign users to specific workflow instances.
• Data & Approvals:
  • Submit data to a workflow block instance.
  • Submit approval or rejection messages to a workflow block.
• Auditing & Assets:
  • Fetch the complete audit trail for a workflow instance.
  • List all assets that have been issued from DOVU workflows.
• Schema Management: Get and validate data against various DOVU schemas.

🌐 Supported Networks

• Hedera Mainnet
• Hedera Testnet

🛠️ Prerequisites

• Node.js 18.0.0 or higher
• Optional: Bun 1.0.0 or higher (alternative runtime)

📦 Installation

# Clone the repository
git clone https://github.com/hedera-mcp/hedera-mcp-server.git
cd hedera-mcp-server

# Install dependencies with npm
npm install

# Or with Bun
bun install

⚙️ Server Configuration

Default configuration includes:

• Default Network: Hedera Mainnet
• Server Port: 3001
• Server Host: 0.0.0.0

These values are hardcoded in the application. If you need to modify them, you can edit the following files:

• For chain configuration: src/core/chains.ts
• For server configuration: src/server/http-server.ts

Environment Variables

The server supports loading configuration from environment variables:

• PRIVATE_KEY: Required private key in ECDSA Format for any blockchain operations that involve signing transactions (e.g., transferring tokens, interacting with smart contracts that modify state). This is the sole method for providing a private key. If this environment variable is not set when a transaction-signing tool is invoked, the tool will return an error message instructing the AI assistant to ask the user to set the PRIVATE_KEY environment variable and restart the MCP server.
• HEDERA_OPERATOR_ID: Optional operator ID for Hedera operations.
• HEDERA_PRIVATE_KEY: Optional private key in DER Format for Hedera operations.

Create a .env file in the root directory based on the .env.example template:

# .env.example
PRIVATE_KEY=your_private_key_here
HEDERA_OPERATOR_ID=your_hedera_operator_id_here
HEDERA_PRIVATE_KEY=your_hedera_private_key_here

SECURITY WARNING: Never commit your actual private key to version control. The .env file is included in .gitignore by default.

🚀 Usage

Using with Claude Desktop

1. Install the Claude Desktop.
2. Go to Settings > Developer > Edit Config.
3. Add the following to the mcpServers section:

{
  "mcpServers": {
    "hedera": {
      "command": "npx",
      "args": [
        "-y",
        "@hedera-mcp/hedera-mcp-server"
      ],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "HEDERA_OPERATOR_ID": "your_hedera_operator_id_here",
        "HEDERA_PRIVATE_KEY": "your_hedera_private_key_here"
      }
    }
  }
}

4. Save the configuration file and restart Claude. When done, Claude will add new prompts, resources and tools. To access prompts, click "+" button in the bottom left corner. And then "Add from hedera".

From there, click "Add from hedera" to and for example, add a "my_wallet_address" prompt. Claude should invoke now get_address_from_private_key tool and return the wallet address. Sometimes, model may fail to understand tbe prompt or random question. Try to add a bit more context or retry with extensive thinking option.

All tools available could be found by clicking "Search And Tools" button and then "hedera".

Running the Server Locally

Start the server using stdio (for embedding in CLI tools):

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

Or start the HTTP server with SSE for web applications:

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

Connecting to the Server

Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the MCP Inspector.

Connecting from Cursor

To connect to the MCP server from Cursor:

1. Open Cursor and go to Settings (gear icon in the bottom left)
2. Scroll down to "MCP" section
3. Click "Add new Global MCP server"
4. In mcp.json tab add the following configuration

Option 1: Use NPM (for published versions)

{
  "mcpServers": {
    "hedera": {
      "command": "npx",
      "args": [
        "-y",
        "@hedera-mcp/hedera-mcp-server"
      ],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "HEDERA_OPERATOR_ID": "your_hedera_operator_id_here",
        "HEDERA_PRIVATE_KEY": "your_hedera_private_key_here"
      }
    }
  }
}

✅ Use Option 2 if there is any error.

Option 2: Use Local Path (for development)

{
  "mcpServers": {
    "hedera": {
      "command": "npx",
      "args": [
        "-y",
        "../hedera-mcp-server" // Relative path to the hedera-mcp-server directory
      ],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "HEDERA_OPERATOR_ID": "your_hedera_operator_id_here",
        "HEDERA_PRIVATE_KEY": "your_hedera_private_key_here"
      }
    }
  }
}

⚠️ Use this if you're developing locally or the package is throwing some error. Make sure the hedera-mcp-server directory is cloned one level up from your project.

Example: HTTP Mode with SSE

If you're developing a web application and want to connect to the HTTP server with Server-Sent Events (SSE), you can use this configuration:

{
  "mcpServers": {
    "hedera-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

This connects directly to the HTTP server's SSE endpoint, which is useful for:

• Web applications that need to connect to the MCP server from the browser
• Environments where running local commands isn't ideal
• Sharing a single MCP server instance among multiple users or applications

To use this configuration:

1. Create a .cursor directory in your project root if it doesn't exist
2. Save the above JSON as mcp.json in the .cursor directory
3. Restart Cursor or open your project
4. Cursor will detect the configuration and offer to enable the server(s)

Example: Using the MCP Server in Cursor

After configuring the MCP server with mcp.json, you can easily use it in Cursor. Here's an example workflow:

// blockchain-example.js
async function main() {
  try {
    // Get Hedera balance for an address
    console.log("Getting Hedera balance for 0.0.123456 or 0x123456789987654321123456789");
    
    // When using with Cursor, you can simply ask Cursor to:
    // "Check the Hedera balance of 0.0.123456 on mainnet"
    // Or "Transfer 0.1 Hedera from my wallet to 0x123456789987654321123456789"
    
    // Cursor will use the MCP server to execute these operations 
    // without requiring any additional code from you
    
    // This is the power of the MCP integration - your AI assistant
    // can directly interact with blockchain data and operations
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. With the file open in Cursor, you can ask Cursor to:

   • "Check the current Hedera balance of 0.0.123456 on mainnet"
   • "Show me the latest block on Hedera"
   • "Check if 0.0.123456 is a contract address"
   • "Transfer 0.1 Hedera from my wallet to 0.0.123456789987654321123456789"
   • "Check the Hedera transaction status of 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

3. Cursor will use the MCP server to execute these operations and return the results directly in your conversation.

The MCP server handles all the blockchain communication while allowing Cursor to understand and execute blockchain-related tasks through natural language.

Example: Getting a Token Balance

// Example of using the MCP client to check a token balance
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0.0.1456986", // WHBAR on Hedera
  ownerAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", 
  network: "hedera"
});

console.log(result);
// {
//   tokenAddress: "0.0.1456986",
//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "hedera",
//   raw: "1000000000",
//   formatted: "1000",
//   symbol: "WHBAR",
//   decimals: 8
// }

📚 API Reference

Network & Blockchain Tools

Account & Transaction Tools

Token Tools (Fungible, NFT, HTS, ERC)

Smart Contract Tools

DeFi (DexScreener) Tools

DOVU OS Tools

🔗 Resources

The server exposes blockchain data through the following MCP resource URIs.

Blockchain Resources

🔒 Security Considerations

• Private keys are used only for transaction signing and are never stored by the server
• Consider implementing additional authentication mechanisms for production use
• Use HTTPS for the HTTP server in production environments
• Implement rate limiting to prevent abuse
• For high-value services, consider adding confirmation steps

📁 Project Structure

hedera-mcp-server/
├── src/
│   ├── index.ts            # Main stdio server entry point
│   ├── server/             # Server-related files
│   │   ├── http-server.ts     # HTTP server with SSE
│   │   └── server.ts          # General server setup
│   ├── core/
│   │   ├── chains.ts          # Chain definitions and utilities
│   │   ├── config.ts          # MCP configuration
│   │   ├── resources.ts       # MCP resources implementation
│   │   ├── prompts.ts         # MCP prompts implementation
│   │   └── services/          # Core blockchain services
│   │   │    ├── index.ts          # Operation exports
│   │   │    ├── balance.ts        # Balance services
│   │   │    ├── transfer.ts       # Token transfer services
│   │   │    ├── utils.ts          # Utility functions
│   │   │    ├── tokens.ts         # Token metadata services
│   │   │    ├── contracts.ts      # Contract interactions
│   │   │    ├── transactions.ts   # Transaction services
│   │   │    └── blocks.ts         # Block services
│   │   │    └── clients.ts        # RPC client utilities
│   │   ├── tools/             # Tools services
│   │        ├── index.ts          # Tools exports
│   │        ├── network.ts        # Network and Block Tools
│   │        ├── token.ts          # Token Tools
│   │        ├── transaction.ts    # Transaction Tools
│   │        ├── deployERC20.ts    # Deploy ERC20 Tools
│   │        ├── deployERC721.ts   # Deploy ERC721 Tools
│   │        ├── dexscreener.ts    # Dexscreener Tools
│   │        └── dovu.ts           # Dovu OS Tools
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development

To modify or extend the server:

1. Add new services in the appropriate file under src/core/services/
2. Add and export new tools in src/core/tools/
3. Register new resources in src/core/resources.ts
4. To change server configuration, edit the hardcoded values in src/server/http-server.ts

📄 License

This project is licensed under the terms of the .