{
  "markdown": "# hedera-mcp\n\n![hedera-mcp](./logo.svg)\n\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.ExpertVagabond%2Fhedera--mcp-3ec6a8)](https://registry.modelcontextprotocol.io/v0/servers?search=hedera-mcp)\n[![npm](https://img.shields.io/npm/v/@purplesquirrel/hedera-mcp?color=3ec6a8&label=npm)](https://www.npmjs.com/package/@purplesquirrel/hedera-mcp)\n[![license](https://img.shields.io/badge/license-MIT-555)](./LICENSE)\n\n**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 **73 MCP tools** any AI agent (Claude, Cursor, etc.) can call.\n\n> **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.\n\n---\n\n## Why this exists\n\nThe 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.\n\n| Service | Official starter MCP | **hedera-mcp** |\n|---|---|---|\n| Account | balance | create, transfer, update, delete, allowances, info, balances, NFTs |\n| Token (HTS) | transfer, deploy | create FT/NFT, mint, burn, transfer, associate, freeze, KYC, pause, wipe, delete, info |\n| Consensus (HCS) | — | create/update/delete topic, submit + read messages |\n| Smart contract | — | deploy, execute, eth_call read, info |\n| File | — | create, append, delete, info |\n| Schedule | — | create, sign, delete, info |\n| Network | — | tx lookup, nodes, fees, supply, exchange rate, decode |\n\n## Security model\n\n- **Reads** → public Mirror Node REST. No keys, no account required.\n- **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.\n- The only optional environment input is `HEDERA_OPERATOR_ID` — an **account id**, used as the default payer/treasury when building. Never a key.\n\nThis mirrors the posture of [goat-network-mcp](https://github.com/ExpertVagabond/goat-network-mcp): safe to run anywhere, safe to give to an autonomous agent.\n\nPublished on npm and the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.ExpertVagabond/hedera-mcp`.\n\n## Install\n\nRun directly with npx (no clone needed):\n\n```bash\nnpx @purplesquirrel/hedera-mcp\n```\n\nOr from source:\n\n```bash\nnpm install\nnpm run build\n```\n\n## Configure (Claude Desktop / Claude Code)\n\n```json\n{\n  \"mcpServers\": {\n    \"hedera\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@purplesquirrel/hedera-mcp\"],\n      \"env\": {\n        \"HEDERA_NETWORK\": \"testnet\",\n        \"HEDERA_OPERATOR_ID\": \"0.0.1234\"\n      }\n    }\n  }\n}\n```\n\n| Env var | Default | Notes |\n|---|---|---|\n| `HEDERA_NETWORK` | `testnet` | `mainnet` \\| `testnet` \\| `previewnet` |\n| `HEDERA_OPERATOR_ID` | _(unset)_ | Optional default payer/treasury **account id** (not a key) |\n| `HEDERA_MIRROR_URL` | per-network | Override Mirror Node REST base (e.g. a private/HGraph node) |\n\n## Build-only workflow\n\n```\nagent calls hedera_create_fungible_token\n        │\n        ▼\nhedera-mcp builds + freezes the TokenCreateTransaction\n        │\n        ▼\nreturns base64 (unsigned)  ──►  you sign in HashPack / SDK / CLI  ──►  submit to Hedera\n```\n\nInspect anything before signing:\n\n```\nhedera_decode_transaction { transactionBase64: \"<bytes>\" }\n→ { type: \"TokenCreateTransaction\", transactionId, nodeAccountIds, maxTransactionFee, ... }\n```\n\n## Tool catalog (73)\n\n**Account (8):** create_account · transfer_hbar · update_account · delete_account · approve_hbar_allowance · get_account_info · get_account_balance · get_account_nfts\n\n**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\n\n**Consensus / HCS (6):** create_topic · submit_message · update_topic · delete_topic · get_topic_info · get_topic_messages\n\n**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)\n\n**File (4):** create_file · append_file · update_file · delete_file\n\n**Schedule (4):** create_schedule · sign_schedule · delete_schedule · get_schedule_info\n\n**Network / utility (7):** prng · get_transaction · get_network_nodes · get_exchange_rate · get_network_supply · get_network_fees · decode_transaction\n\n**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\n\n## Resources (4)\n\nBesides tools, the server exposes addressable, keyless MCP **resources** agents can read by URI:\n\n`hedera://network/exchange-rate` · `hedera://network/supply` · `hedera://account/{accountId}` · `hedera://token/{tokenId}`\n\n## Examples & learning\n\n- [`examples/TUTORIAL.md`](examples/TUTORIAL.md) — **Build on Hedera in 5 prompts** (the certified→shipping learning path)\n- [`examples/agent-demo.md`](examples/agent-demo.md) — wire into Claude Desktop and build by asking; `node examples/agent-sim.mjs` prints a reproducible agent transcript\n- [`examples/scenarios/`](examples/scenarios/) — unique use cases, each runnable + Mirror Node-verified: **HCS notary**, **AI agent audit trail**, **agent-to-agent payments**, **self-taxing token**\n\n## Verification\n\n- `npm run lint` / `npm run build` — clean against `@hashgraph/sdk` 2.81.0\n- `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**\n- `node test-live.mjs` — **10/10 write paths executed on testnet**, Mirror Node-verified\n- `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)\n- `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`\n- `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)\n- `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\n\n## Development\n\n```bash\nnpm run lint       # tsc --noEmit\nnpm run build      # compile to dist/\nnode test-smoke.mjs    # MCP stdio: live Mirror Node read + build-only write + decode\nnode demo.mjs          # narrated \"developer's first session\" walkthrough (build-only)\nnode test-execute.mjs  # LIVE testnet submit (needs a throwaway key in .env — see below)\n```\n\n### Live execution verification\n\n`test-execute.mjs` proves the build-only output is real: the MCP server builds an\nunsigned transaction, the harness signs it with a **throwaway testnet key from `.env`**\nand submits it, then confirms the result independently via Mirror Node. The server\nstays build-only the whole time — only the test harness ever touches a key.\n\n```\nHEDERA_NETWORK=testnet\nHEDERA_OPERATOR_ID=0.0.xxxxxx\nHEDERA_OPERATOR_KEY=302e0201...    # rotate/discard after verifying\n```\n\nGet a free testnet account at [portal.hedera.com](https://portal.hedera.com).\n\nBuilt on [`@hashgraph/sdk`](https://www.npmjs.com/package/@hashgraph/sdk) and [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk).\n\n## Releasing\n\nBump 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.\n\n```bash\nnpm run build\nnpm publish --access public\n```\n\nThen 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:\n\n```bash\nmkdir -p /tmp/hedera-publish\ncp server.json /tmp/hedera-publish/\ncd /tmp/hedera-publish\nmcp-publisher login github      # device-code flow, authorize as ExpertVagabond\nmcp-publisher publish\n```\n\nVerify all three surfaces are aligned:\n\n```bash\ncurl -s \"https://registry.modelcontextprotocol.io/v0/servers?search=ExpertVagabond/hedera-mcp&version=latest\" | jq '.servers[0].server | {name, version}'\nnpm view @purplesquirrel/hedera-mcp version\n```\n\n## License\n\nMIT © Matthew Karsten\n",
  "bytes": 10135,
  "sha": "b8682f6fd9b89044ee002341a84360231017119f40b006976b03c6916c752abe",
  "repo_slug": "expertvagabond/hedera-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_expertvagabond_hedera_mcp_008486e3/readme"
}