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

Tool Name	Description	Key Parameters
get_chain_info	Get information about a network, including EVM and Hedera data.	network
get_supported_networks	Get a list of supported EVM and Hedera networks.	—
get_block_by_number	Get a block by its number.	blockNumber, network
get_block_by_hash	Get a block by its hash.	blockHash, network
get_latest_block	Get the latest block from the network.	network
get_block_number	Get the current block number.	network
get_blocks_by_timestamp	Get blocks within a Hedera timestamp range.	fromTimestamp, toTimestamp, limit, network
get_block_by_timestamp	Get a block by a specific Hedera consensus timestamp.	timestamp, network

Account & Transaction Tools

Tool Name	Description	Key Parameters
get_balance	Get the native token (HBAR) balance for an address (EVM or Hedera format).	address, network, preferMirrorNode, timeout
get_account_portfolio	Get a complete account portfolio (HBAR, tokens, NFTs).	addressOrId, network, includeNFTs, nftLimit
get_account_transactions	Get transactions for a Hedera account with filtering.	accountId, limit, order, timestamp, transactiontype, result, type, network
get_account_transaction_count	Get the total number of transactions for a Hedera account.	accountId, transactiontype, result, type, timestamp, network
get_account_activity_summary	Get a summary of recent account activity.	accountId, days, network
get_transaction	Get a transaction by its hash (EVM) or ID (Hedera).	identifier, network
get_transaction_receipt	Get a transaction receipt by its hash (EVM) or ID (Hedera).	identifier, network
check_address_format	Check the format of an address (EVM or Hedera).	address
convert_address_format	Convert between Hedera ID and EVM address formats.	identifier, network
get_address_from_private_key	Get the EVM address derived from a private key.	—

Token Tools (Fungible, NFT, HTS, ERC)

Tool Name	Description	Key Parameters
deploy_erc20	Deploys a new ERC20 token.	name, symbol, initialSupply, decimals, network
deploy_erc721	Deploys a new ERC721 (NFT) token.	name, symbol, baseURI_, network
get_token_balance	Get token balance (ERC20 or Hedera) for an address.	tokenAddressOrId, ownerAddressOrId, network, preferMirrorNode
get_token_info	Get comprehensive information about an ERC20 or Hedera token.	tokenAddressOrId, network
get_account_tokens	Get all tokens owned by an account.	addressOrId, network
get_account_nfts	Get NFTs owned by an account.	addressOrId, network, tokenId, limit, order
check_nft_ownership	Check if an address owns a specific NFT.	tokenAddressOrId, tokenId, ownerAddressOrId, network
get_nft_balance	Get the total number of NFTs from a collection owned by an address.	tokenAddressOrId, ownerAddressOrId, network
get_nft_info	Get detailed information about a specific NFT (ERC721).	tokenAddress, tokenId, network
get_erc1155_balance	Get the balance of a specific ERC1155 token ID.	tokenAddress, tokenId, ownerAddress, network
get_erc1155_token_uri	Get the metadata URI for an ERC1155 token.	tokenAddress, tokenId, network
transfer_hbar	Transfer native HBAR tokens.	to, amount, network
transfer_erc20	Transfer ERC20 tokens.	tokenAddress, toAddress, amount, network
transfer_nft	Transfer an NFT (ERC721).	tokenAddress, tokenId, toAddress, network
transfer_erc1155	Transfer ERC1155 tokens.	tokenAddress, tokenId, amount, toAddress, network
hts_token_transfer	Transfer a Hedera (HTS) fungible token.	receiver, tokenId, amount, network
hts_nft_transfer	Transfer a Hedera (HTS) NFT.	receiver, tokenId, serialNumber, network
approve_token_spending	Approve an address to spend your ERC20 tokens.	tokenAddress, spenderAddress, amount, network

Smart Contract Tools

Tool Name	Description	Key Parameters
verify_erc20_contract_locally	Verifies a deployed ERC20 contract's parameters.	contractAddress, name, symbol, initialSupply, decimals, network
verify_erc20_contract	Verifies a deployed ERC20 contract on a block explorer.	contractAddress, contractName, network
verify_erc721_contract_locally	Verifies a deployed ERC721 contract's parameters.	contractAddress, name, symbol, baseURI_, network
read_contract	Read data from a smart contract (EVM or Hedera).	contractAddress, abi, functionName, args, network
write_contract	Write data to a smart contract (EVM or Hedera).	contractAddress, abi, functionName, args, gas, payableAmount, network
is_contract	Check if an address or ID is a smart contract.	addressOrId, network
get_contract_info	Get detailed information about a Hedera native contract.	contractId, network
get_contract_results	Get execution results for a Hedera native contract.	contractId, limit, order, network
estimate_gas	Estimate the gas cost for an EVM transaction.	to, value, data, network

DeFi (DexScreener) Tools

Tool Name	Description	Key Parameters
dex_search_pairs	Search for token pairs by token name, symbol, or address.	query
dex_get_token_pairs	Get all pairs for specific token addresses.	tokenAddresses
dex_get_pairs_by_address	Get pair information by a specific pair address.	chainId, pairAddress
dex_get_token_profile	Get a token's profile information.	chainId, tokenAddress
dex_get_latest_token_profiles	Get recently updated token profiles.	—
dex_get_top_boosted_tokens	Get top boosted tokens on DexScreener.	—
dex_get_orders_by_chain	Get trading orders/activity by chain.	chainId, tokenAddress

DOVU OS Tools

Tool Name	Description	Key Parameters
get_dovu_workflows	Get a list of workflows from DOVU.	filter
publish_dovu_workflow	Publish a workflow on DOVU.	payload, authToken
get_dovu_workflow_owner_instance_details	Get details for a specific workflow owner instance.	workflowInstanceId
submit_data_workflow_block_instance	Submit JSON data to a workflow block instance.	workflowBlockInstanceId, data, token
submit_approval_workflow_block_instance	Submit an approval or rejection to a workflow block.	workflowBlockInstanceId, approve, message, token
register_dovu_actor	Register a new actor in the DOVU OS.	name, email, password, password_confirmation, role
dovu_login	Login to DOVU OS to get an authentication token.	email, password
get_dovu_audit_trail	Get the audit trail of a specific workflow instance.	workflowInstanceId

---

🔗 Resources

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

Blockchain Resources

Resource URI Pattern	Description
hedera://{network}/account/{accountId}	Account info and balances
hedera://{network}/token/{tokenId}	Token info and metadata
hedera://{network}/token/{tokenId}/balanceOf/{accountId}	Token balance of account
hedera://{network}/transaction/{transactionId}	Transaction record and receipt

🔒 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 MIT License.