Skip to main content
Glama

hedera-mcp

hedera-mcp

MCP Registry npm license

Comprehensive Model Context Protocol server for Hedera (Hashgraph). Full coverage of every core Hedera service — Account, Token (HTS), Consensus (HCS), Smart Contract (EVM), File, Schedule, and Network — exposed as 79 MCP tools any AI agent (Claude, Cursor, etc.) can call.

Build-only. Never holds keys. Reads hit the public Mirror Node REST API (no auth). Writes return an unsigned, frozen transaction (base64) for you to sign and submit with your own wallet/SDK/CLI. This server never sees a private key and never executes anything.


Why this exists

The official Hedera Agent Kit ships a preconfigured MCP server, but its tool surface is intentionally small (balance, transfer, deploy). This server fills the gap with end-to-end coverage of the Hedera API, organized for developer education and agent-driven onboarding — so a developer can go from "certified" to "shipping their first HTS token / HCS topic / contract" inside a single AI session.

Service

Official starter MCP

hedera-mcp

Account

balance

create, transfer, update, delete, allowances, info, balances, NFTs

Token (HTS)

transfer, deploy

create FT/NFT, mint, burn, transfer, associate, freeze, KYC, pause, wipe, delete, info

Consensus (HCS)

—

create/update/delete topic, submit + read messages

Smart contract

—

deploy, execute, eth_call read, info

File

—

create, append, delete, info

Schedule

—

create, sign, delete, info

Network

—

tx lookup, nodes, fees, supply, exchange rate, decode

Related MCP server: KawaFi

Security model

  • Reads → public Mirror Node REST. No keys, no account required.

  • Writes → the tool constructs the transaction, freezes it for offline signing, and returns base64 bytes plus a human summary. You inspect it (hedera_decode_transaction), then sign and submit yourself.

  • The only optional environment input is HEDERA_OPERATOR_ID — an account id, used as the default payer/treasury when building. Never a key.

This mirrors the posture of goat-network-mcp: safe to run anywhere, safe to give to an autonomous agent.

Published on npm and the MCP Registry as io.github.ExpertVagabond/hedera-mcp.

Install

Run directly with npx (no clone needed):

npx @purplesquirrel/hedera-mcp

Or from source:

npm install
npm run build

Configure (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "hedera": {
      "command": "npx",
      "args": ["-y", "@purplesquirrel/hedera-mcp"],
      "env": {
        "HEDERA_NETWORK": "testnet",
        "HEDERA_OPERATOR_ID": "0.0.1234"
      }
    }
  }
}

Env var

Default

Notes

HEDERA_NETWORK

testnet

mainnet | testnet | previewnet

HEDERA_OPERATOR_ID

(unset)

Optional default payer/treasury account id (not a key)

HEDERA_MIRROR_URL

per-network

Override Mirror Node REST base (e.g. a private/HGraph node)

Build-only workflow

agent calls hedera_create_fungible_token
        │
        ▼
hedera-mcp builds + freezes the TokenCreateTransaction
        │
        ▼
returns base64 (unsigned)  ──►  you sign in HashPack / SDK / CLI  ──►  submit to Hedera

Inspect anything before signing:

hedera_decode_transaction { transactionBase64: "<bytes>" }
→ { type: "TokenCreateTransaction", transactionId, nodeAccountIds, maxTransactionFee, ... }

Tool catalog (79)

Account (8): create_account · transfer_hbar · update_account · delete_account · approve_hbar_allowance · get_account_info · get_account_balance · get_account_nfts

Token / HTS (23): create_fungible_token · create_nft_collection · mint_fungible · mint_nft · burn_token · transfer_token · transfer_nft · associate_token · dissociate_token · freeze_token_account · unfreeze_token_account · grant_kyc · revoke_kyc · pause_token · unpause_token · wipe_token · delete_token · update_token · token_airdrop · reject_token · approve_token_allowance · approve_nft_allowance · get_token_info · get_nft_info

Consensus / HCS (6): create_topic · submit_message · update_topic · delete_topic · get_topic_info · get_topic_messages

Smart contract / EVM (6): deploy_contract · execute_contract · update_contract · delete_contract · query_contract · get_contract_info — execute_contract & query_contract are ABI-aware (pass { abi, functionName, args }; calldata encoded + results decoded automatically)

File (4): create_file · append_file · update_file · delete_file

Schedule (4): create_schedule · sign_schedule · delete_schedule · get_schedule_info

Network / utility (7): prng · get_transaction · get_network_nodes · get_exchange_rate · get_network_supply · get_network_fees · decode_transaction

Analytics (Mirror Node reads, 14): get_block · get_blocks · get_account_transactions · get_token_balances · get_token_nfts · get_nft_history · get_account_allowances · get_account_token_allowances · get_account_nft_allowances · get_contract_results · get_contract_state · get_network_stake · search_accounts_by_pubkey · get_account_by_evm

Resources (4)

Besides tools, the server exposes addressable, keyless MCP resources agents can read by URI:

hedera://network/exchange-rate · hedera://network/supply · hedera://account/{accountId} · hedera://token/{tokenId}

Examples & learning

  • examples/TUTORIAL.md — Build on Hedera in 5 prompts (the certified→shipping learning path)

  • examples/agent-demo.md — wire into Claude Desktop and build by asking; node examples/agent-sim.mjs prints a reproducible agent transcript

  • examples/scenarios/ — unique use cases, each runnable + Mirror Node-verified: HCS notary, AI agent audit trail, agent-to-agent payments, self-taxing token

Verification

  • npm run lint / npm run build — clean against @hashgraph/sdk 2.81.0

  • node test-battle.mjs — 72/73 in the auto-discovery suite (1 skip: query_contract needs a known ABI, verified separately) → all 73 tools verified (pre-MPP; 79 with the MPP charge tools)

  • node test-live.mjs — 10/10 write paths executed on testnet, Mirror Node-verified

  • node test-battle-live.mjs — battle mode: 31/31 operations on testnet across two accounts (full token lifecycle incl. freeze/KYC/pause/wipe, NFT, topic, file, scheduled transfer requiring a 2nd signer, PRNG), Mirror Node-verified. Re-run signed by an ED25519 operator: 31/31 still pass — non-EVM tools are key-type-agnostic (the server holds no keys; EVM tools inherently require ECDSA per Hedera's EVM-alias rule)

  • node test-contract.mjs — real Solidity contract compiled → deployed → executed → read end-to-end (store(42) → retrieve() = 42), confirming the full EVM path and query_contract

  • node test-contract-abi.mjs — ABI-aware query_contract: fed a raw ABI, it auto-encodes/decodes — answer() → 73 (uint), title() → "hedera-mcp" (string), ping() → 73 (pure)

  • node test-edge-cases.mjs — 12/12 edge paths on testnet the happy-path suites miss: large file via create+append (>1 tx chunk), HCS message >1024 B auto-chunked across 2 mirror entries (reassembled to 1200 B), NFT collection with a 10% royalty + 1ℏ fallback custom fee, delegated approved spend (operator approves B → B pulls 200 paying its own fee), HBAR → fresh ED25519 alias auto-account-create, and a decode_transaction round-trip

Development

npm run lint       # tsc --noEmit
npm run build      # compile to dist/
node test-smoke.mjs    # MCP stdio: live Mirror Node read + build-only write + decode
node demo.mjs          # narrated "developer's first session" walkthrough (build-only)
node test-execute.mjs  # LIVE testnet submit (needs a throwaway key in .env — see below)

Live execution verification

test-execute.mjs proves the build-only output is real: the MCP server builds an unsigned transaction, the harness signs it with a throwaway testnet key from .env and submits it, then confirms the result independently via Mirror Node. The server stays build-only the whole time — only the test harness ever touches a key.

HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.xxxxxx
HEDERA_OPERATOR_KEY=302e0201...    # rotate/discard after verifying

Get a free testnet account at portal.hedera.com.

Built on @hashgraph/sdk and @modelcontextprotocol/sdk.

Releasing

Bump the version in package.json, server.json (both top-level version and packages[0].version), and src/index.ts; update CHANGELOG.md; then publish to npm and the MCP Registry.

npm run build
npm publish --access public

Then sync the MCP Registry. Run mcp-publisher from /tmp, not from the project directory — on this setup the project lives on a volume where the publisher can't persist its OAuth token (operation not permitted), which silently fails the publish step. Copying server.json to a writable scratch dir sidesteps it:

mkdir -p /tmp/hedera-publish
cp server.json /tmp/hedera-publish/
cd /tmp/hedera-publish
mcp-publisher login github      # device-code flow, authorize as ExpertVagabond
mcp-publisher publish

Verify all three surfaces are aligned:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=ExpertVagabond/hedera-mcp&version=latest" | jq '.servers[0].server | {name, version}'
npm view @purplesquirrel/hedera-mcp version

License

MIT © Matthew Karsten

Available Tools

73 tools
hedera_append_fileC

Build (unsigned) an append to an existing file (for bytecode larger than one transaction).

Inputs: fileId (required), contents (required), payerAccountId.

hedera_approve_hbar_allowanceA

Build (unsigned) an HBAR allowance granting a spender the right to spend from an owner account.

Inputs: amountHbar (required), spenderAccountId (required), ownerAccountId, payerAccountId.

hedera_approve_nft_allowanceC

Build (unsigned) an NFT allowance for all serials of a collection (approve-for-all).

Inputs: tokenId (required), spenderAccountId (required), ownerAccountId, payerAccountId.

hedera_approve_token_allowanceC

Build (unsigned) a fungible-token spending allowance for a spender.

Inputs: amount (required), tokenId (required), spenderAccountId (required), ownerAccountId, +1 more.

hedera_associate_tokenB

Build (unsigned) a token association so an account can hold the given token(s).

Inputs: tokenIds (required), accountId (required), payerAccountId.

hedera_burn_tokenC

Build (unsigned) a burn of fungible amount or specific NFT serials.

Inputs: tokenId (required), amount, serials, payerAccountId.

hedera_create_accountA

Build (unsigned) a new Hedera account with a given public key and optional initial HBAR balance.

Inputs: publicKey (required), memo, payerAccountId, initialBalanceHbar, +1 more.

hedera_create_fileB

Build (unsigned) a new file. Useful for storing compiled contract bytecode before deployment.

Inputs: contents (required), key, memo, payerAccountId.

hedera_create_fungible_tokenA

Build (unsigned) a new fungible token (HTS). Treasury defaults to the payer.

Inputs: name (required), symbol (required), memo, kycKey, +13 more.

hedera_create_nft_collectionB

Build (unsigned) a new non-fungible token collection (HTS). A supply key is required to mint.

Inputs: name (required), symbol (required), supplyKey (required), memo, +8 more.

hedera_create_scheduleB

Build (unsigned) a scheduled HBAR transfer — wraps an inner transfer so multiple parties can sign before it executes.

Inputs: amountHbar (required), toAccountId (required), memo, adminKey, +3 more.

hedera_create_topicC

Build (unsigned) a new HCS topic for ordered, timestamped messages.

Inputs: memo, adminKey, submitKey, payerAccountId.

hedera_decode_transactionA

Decode a base64 transaction (e.g. one built by this server) into a human-readable summary — useful for review before signing.

Inputs: transactionBase64 (required).

hedera_delete_accountB

Build (unsigned) an account deletion, transferring the remaining balance to another account.

Inputs: accountId (required), transferAccountId (required), payerAccountId.

hedera_delete_contractC

Build (unsigned) a contract deletion, transferring any balance to an account.

Inputs: contractId (required), transferAccountId (required), payerAccountId.

hedera_delete_fileC

Build (unsigned) a file deletion.

Inputs: fileId (required), payerAccountId.

hedera_delete_scheduleC

Build (unsigned) a deletion of a scheduled transaction (requires admin key).

Inputs: scheduleId (required), payerAccountId.

hedera_delete_tokenC

Build (unsigned) a token deletion (requires the admin key to sign).

Inputs: tokenId (required), payerAccountId.

hedera_delete_topicA

Build (unsigned) a deletion of an HCS topic (requires admin key).

Inputs: topicId (required), payerAccountId.

hedera_deploy_contractB

Build (unsigned) a contract deployment from bytecode already stored in a Hedera File (see hedera_create_file).

Inputs: gas (required), bytecodeFileId (required), adminKey, payerAccountId, +2 more.

hedera_dissociate_tokenC

Build (unsigned) a token dissociation.

Inputs: tokenIds (required), accountId (required), payerAccountId.

hedera_execute_contractA

Build (unsigned) a state-changing contract call. Pass { abi, functionName, args } for automatic encoding, or raw functionParametersBase64.

Inputs: gas (required), contractId (required), abi, args, +4 more.

hedera_freeze_token_accountC

Build (unsigned): Freeze an account for a token (blocks transfers).

Inputs: tokenId (required), accountId (required), payerAccountId.

hedera_get_account_allowancesB

Read an account's active HBAR (crypto) allowances from the Mirror Node.

Inputs: accountId (required).

hedera_get_account_balanceA

Read an account's HBAR and token balances from the Mirror Node.

Inputs: accountId (required).

hedera_get_account_by_evmA

Resolve a Hedera account from a 0x EVM address via the Mirror Node.

Inputs: evmAddress (required).

hedera_get_account_infoA

Read full account info (key, balance, memo, auto-renew, associations) from the Mirror Node.

Inputs: accountId (required).

hedera_get_account_nft_allowancesB

Read an account's active NFT (approve-for-all) allowances from the Mirror Node.

Inputs: accountId (required).

hedera_get_account_nftsB

List NFTs owned by an account from the Mirror Node.

Inputs: accountId (required), limit.

hedera_get_account_token_allowancesB

Read an account's active fungible-token allowances from the Mirror Node.

Inputs: accountId (required).

hedera_get_account_transactionsC

List recent transactions for an account from the Mirror Node.

Inputs: accountId (required), limit.

hedera_get_blockB

Read a block by number or hash from the Mirror Node.

Inputs: numberOrHash (required).

hedera_get_blocksC

List recent blocks from the Mirror Node.

Inputs: limit.

hedera_get_contract_infoB

Read contract info (admin key, bytecode metadata, EVM address) from the Mirror Node.

Inputs: contractId (required).

hedera_get_contract_resultsC

List recent execution results for a contract from the Mirror Node.

Inputs: contractId (required), limit.

hedera_get_contract_stateC

Read a contract's current storage slots from the Mirror Node.

Inputs: contractId (required), limit.

hedera_get_exchange_rateA

Read the current HBAR↔USD exchange rate from the Mirror Node.

Inputs: no named parameters.

hedera_get_network_feesA

Read the current network fee schedule from the Mirror Node.

Inputs: no named parameters.

hedera_get_network_nodesA

List the network's consensus nodes and stake from the Mirror Node.

Inputs: no named parameters.

hedera_get_network_stakeA

Read network-wide staking info (total staked, reward rate) from the Mirror Node.

Inputs: no named parameters.

hedera_get_network_supplyA

Read total/circulating HBAR supply from the Mirror Node.

Inputs: no named parameters.

hedera_get_nft_historyB

Read the transfer/mint history of a specific NFT serial from the Mirror Node.

Inputs: serial (required), tokenId (required).

hedera_get_nft_infoB

Read a specific NFT's info (owner, metadata, serial) from the Mirror Node.

Inputs: serial (required), tokenId (required).

hedera_get_schedule_infoA

Read scheduled-transaction info (signatures, executed status) from the Mirror Node.

Inputs: scheduleId (required).

hedera_get_token_balancesC

List the accounts holding a token and their balances, from the Mirror Node.

Inputs: tokenId (required), limit.

hedera_get_token_infoB

Read token info (type, supply, keys, custom fees) from the Mirror Node.

Inputs: tokenId (required).

hedera_get_token_nftsC

List the minted NFTs (serials) of an NFT collection from the Mirror Node.

Inputs: tokenId (required), limit.

hedera_get_topic_infoC

Read HCS topic info from the Mirror Node.

Inputs: topicId (required).

hedera_get_topic_messagesA

Read recent messages from an HCS topic via the Mirror Node (decodes base64 payloads).

Inputs: topicId (required), limit.

hedera_get_transactionA

Read a transaction's records/results from the Mirror Node by transaction id.

Inputs: transactionId (required).

hedera_grant_kycC

Build (unsigned): Grant KYC to an account for a token.

Inputs: tokenId (required), accountId (required), payerAccountId.

hedera_mint_fungibleC

Build (unsigned) a mint of additional fungible token supply.

Inputs: amount (required), tokenId (required), payerAccountId.

hedera_mint_nftC

Build (unsigned) a mint of one or more NFTs with metadata (e.g. IPFS CIDs).

Inputs: tokenId (required), metadata (required), payerAccountId.

hedera_pause_tokenC

Build (unsigned) a token pause (halts all transfers of the token).

Inputs: tokenId (required), payerAccountId.

hedera_prngA

Build (unsigned) a pseudo-random number generation transaction (native on-chain RNG). Optionally bound to [0, range).

Inputs: range, payerAccountId.

hedera_query_contractA

Read a contract view/pure function via Mirror Node eth_call (keyless, no gas). Pass { abi, functionName, args } for auto encode/decode, or raw dataHex.

Inputs: contractIdOrAddress (required), abi, args, dataHex, +2 more.

hedera_reject_tokenB

Build (unsigned) a token rejection (HIP-904) — returns an unwanted token to its treasury.

Inputs: tokenId (required), ownerAccountId, payerAccountId.

hedera_revoke_kycB

Build (unsigned): Revoke KYC from an account for a token.

Inputs: tokenId (required), accountId (required), payerAccountId.

hedera_search_accounts_by_pubkeyB

Find accounts controlled by a given public key from the Mirror Node.

Inputs: publicKey (required).

hedera_sign_scheduleC

Build (unsigned) a signature add to an existing scheduled transaction.

Inputs: scheduleId (required), payerAccountId.

hedera_submit_messageC

Build (unsigned) a message submission to an HCS topic.

Inputs: message (required), topicId (required), payerAccountId.

hedera_token_airdropB

Build (unsigned) a fungible-token airdrop (HIP-904) — auto-associates recipients without prior opt-in.

Inputs: amount (required), tokenId (required), toAccountId (required), fromAccountId, +1 more.

hedera_transfer_hbarA

Build (unsigned) an HBAR transfer from one account to another.

Inputs: amountHbar (required), toAccountId (required), memo, fromAccountId, +1 more.

hedera_transfer_nftC

Build (unsigned) an NFT transfer of a specific serial between two accounts.

Inputs: serial (required), tokenId (required), toAccountId (required), fromAccountId, +1 more.

hedera_transfer_tokenC

Build (unsigned) a fungible token transfer between two accounts.

Inputs: amount (required), tokenId (required), toAccountId (required), fromAccountId, +1 more.

hedera_unfreeze_token_accountC

Build (unsigned): Unfreeze an account for a token.

Inputs: tokenId (required), accountId (required), payerAccountId.

hedera_unpause_tokenC

Build (unsigned) a token unpause.

Inputs: tokenId (required), payerAccountId.

hedera_update_accountC

Build (unsigned) an account update (memo, auto-association slots).

Inputs: accountId (required), memo, payerAccountId, maxAutomaticTokenAssociations.

hedera_update_contractA

Build (unsigned) an update to a contract's memo or admin key (requires admin key to sign).

Inputs: contractId (required), memo, payerAccountId.

hedera_update_fileC

Build (unsigned) an update that replaces a file's contents and/or memo.

Inputs: fileId (required), memo, contents, payerAccountId.

hedera_update_tokenA

Build (unsigned) an update to a token's name, symbol, memo, or treasury (requires the admin key to sign).

Inputs: tokenId (required), memo, name, symbol, +2 more.

hedera_update_topicC

Build (unsigned) an update to an HCS topic memo.

Inputs: memo (required), topicId (required), payerAccountId.

hedera_wipe_tokenC

Build (unsigned) a wipe of fungible amount or NFT serials from an account.

Inputs: tokenId (required), accountId (required), amount, serials, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 73 tools

    Disambiguation5/5

    Every tool targets a distinct resource and action. The resource type (account, token, topic, contract, file, schedule, etc.) is included in the name, making it impossible to confuse one tool with another.

    Naming Consistency5/5

    All tools follow a strict 'hedera_verb_noun' pattern with lowercase and underscores. No deviations exist, ensuring predictable tool names.

    Tool Count2/5

    73 tools is far beyond the typical 3–15 range. While comprehensive, the sheer number makes the set feel heavy and could overwhelm agents, leading to slower selection.

    Completeness5/5

    The toolset covers nearly every operation on Hedera: accounts, tokens, topics, contracts, files, schedules, network queries, and extras like PRNG and transaction decoding. No obvious gaps exist.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server providing unified access to the Hedera DeFi ecosystem, including SaucerSwap, Bonzo Finance, and Stader. It enables AI assistants to perform real-time data analytics and prepare or execute transactions across multiple decentralized finance platforms.
      17
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Production MCP server giving AI agents metered access to live Hedera blockchain data. Query token prices, screen identities, monitor governance, write tamper-evident HCS compliance records, and analyze smart contracts — all paid in HBAR micropayments per call.
      20
      47 npm
      Academic Free v1.1