hedera-mcp
hedera-mcp is a keyless, build-only MCP server that gives any AI agent full read/write coverage of Hedera (Hashgraph) — it reads via the public Mirror Node and returns unsigned, frozen transactions for you to sign and submit yourself.
Accounts: create, transfer HBAR, update, delete, approve HBAR allowances, and read account info/balances/NFTs
Tokens (HTS): create fungible tokens or NFT collections (with custom fees/royalties), mint, burn, transfer FT/NFT, associate/dissociate, freeze/unfreeze, grant/revoke KYC, pause/unpause, wipe, delete, update, airdrop, reject, and approve FT/NFT allowances
Consensus (HCS): create/update/delete topics, submit messages, and read topic info and messages
Smart contracts (EVM): deploy bytecode, execute state-changing calls, update/delete contracts, and read via ABI-aware
eth_call(query_contract) plus contract infoFiles: create, append, update, and delete files (e.g. storing compiled bytecode)
Schedules: create scheduled (multi-signer) transactions, add signatures, delete, and inspect status
Network/utility: on-chain PRNG, transaction lookup, node list, exchange rate, supply, fee schedule, and decode any built transaction into a human-readable summary
Analytics (Mirror Node reads): blocks, account transactions, token balances/holders, token NFTs, NFT history, account allowances, contract results/state, network stake, pubkey account search, and EVM-address account resolution
Resources: addressable keyless reads — exchange rate, supply,
hedera://account/{id},hedera://token/{id}Safety: never holds or needs a private key; only optional env input is
HEDERA_OPERATOR_ID(an account id, not a key)
Comprehensive integration with the Hedera Hashgraph network, providing tools for managing accounts, tokens (HTS), consensus topics (HCS), smart contracts (EVM), files, schedules, and network queries. Supports operations such as creating, updating, deleting, transferring, and querying assets, as well as reading mirror node data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hedera-mcp get account balance for 0.0.539827"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hedera-mcp
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-mcpOr from source:
npm install
npm run buildConfigure (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 |
|
|
|
| (unset) | Optional default payer/treasury account id (not a key) |
| 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 HederaInspect 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.mjsprints a reproducible agent transcriptexamples/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/sdk2.81.0node test-battle.mjs— 72/73 in the auto-discovery suite (1 skip:query_contractneeds 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-verifiednode 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 andquery_contractnode test-contract-abi.mjs— ABI-awarequery_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 adecode_transactionround-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 verifyingGet 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 publicThen 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 publishVerify 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 versionLicense
MIT © Matthew Karsten
Available Tools
73 toolshedera_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
Scored across 73 tools
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.
All tools follow a strict 'hedera_verb_noun' pattern with lowercase and underscores. No deviations exist, ensuring predictable tool names.
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.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables interactions with the Hedera network, providing tools for wallet creation, balance checking, transaction building, and sending signed transactions.3MIT
- AlicenseBqualityDmaintenanceA 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.17MIT
- AlicenseAqualityBmaintenanceProduction 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.2047 npmAcademic Free v1.1
- AlicenseNot gradedqualityDmaintenanceProvides tools for AI assistants to interact with the Hedera blockchain, enabling account management, consensus messaging, and HBAR transfers. Supports testnet, mainnet, and previewnet.MIT