hedera-mcp

Name: hedera-mcp
Author: ExpertVagabond

本地服务

github.com/ExpertVagabond金融数据012 周前更新

代码仓库

关于 hedera-mcp

hedera-mcp 是面向 Hedera 开发者和 AI Agent 的构建型 MCP 服务，覆盖核心服务与分析读取。写操作仅生成未签名交易，供外部检查、签名和提交。

主要功能

01覆盖 Hedera 核心服务的工具
02无需认证的 Mirror Node 读取
03构建未签名冻结交易
04解码交易以供检查
05可寻址的无密钥资源

适用场景

01准备 Hedera 代币或账户交易
02读取 HCS 主题及消息
03签名前检查交易数据
04查询网络与账户分析数据

MCP 相关

向 MCP 客户端提供 Hedera 工具和资源。读取使用公开的 Mirror Node REST API；写操作返回未签名交易，服务本身不会执行交易。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "expertvagabond-hedera": {
      "command": "npx",
      "args": [
        "-y",
        "@purplesquirrel/hedera-mcp"
      ],
      "env": {
        "HEDERA_NETWORK": "<HEDERA_NETWORK>",
        "HEDERA_OPERATOR_ID": "<HEDERA_OPERATOR_ID>",
        "HEDERA_MIRROR_URL": "<HEDERA_MIRROR_URL>"
      }
    }
  }
}

启动命令npx -y @purplesquirrel/hedera-mcp

需要配置的环境变量

HEDERA_NETWORKmainnet | testnet (default) | previewnet

HEDERA_OPERATOR_IDOptional default payer/treasury account id (not a private key)

HEDERA_MIRROR_URLOptional Mirror Node REST base URL override

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@purplesquirrel/hedera-mcp0.5.0stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
memo	string	否	账户备注
publicKey	string	是	控制新账户的 ED25519 或 ECDSA 公钥（DER 或十六进制）
payerAccountId	string	否	付款方（默认值为 HEDERA_OPERATOR_ID）
initialBalanceHbar	number	否	以 HBAR 计的初始余额（默认值为 0）
maxAutomaticTokenAssociations	integer	否	自动代币关联槽位

详细介绍

hedera-mcp

适用于 Hedera（Hashgraph）的全面 Model Context Protocol 服务。 全面覆盖 Hedera 的所有核心服务——账户、代币（HTS）、共识（HCS）、智能合约（EVM）、文件、计划和网络——以 79 个 MCP 工具的形式开放，供任何 AI Agent（Claude、Cursor 等）调用。

仅构建，不持有密钥。 读取通过公开的 Mirror Node REST API 完成（无需身份验证）。写入会返回未签名、已冻结的交易（base64），由你使用自己的钱包／SDK／CLI 签名并提交。本服务绝不会接触私钥，也不会执行任何操作。

为什么要做这个项目

Hedera 官方 Agent Kit 附带了一个预配置的 MCP 服务，但其工具范围有意保持精简（余额、转账、部署）。本服务通过全面覆盖 Hedera API 来填补这一空缺，并围绕开发者教育和由 Agent 驱动的入门流程进行组织——让开发者只需一次 AI 会话，就能从“获得认证”到“发布首个 HTS 代币／HCS 主题／合约”。

服务	官方入门 MCP	hedera-mcp
账户	余额	创建、转账、更新、删除、授权、信息、余额、NFT
代币（HTS）	转账、部署	创建 FT／NFT、铸造、销毁、转账、关联、冻结、KYC、暂停、清除、删除、信息
共识（HCS）	—	创建／更新／删除主题、提交＋读取消息
智能合约	—	部署、执行、eth_call 读取、信息
文件	—	创建、追加、删除、信息
计划	—	创建、签名、删除、信息
网络	—	交易查询、节点、费用、供应量、汇率、解码

安全模型

读取 → 公开的 Mirror Node REST。无需密钥，也无需账户。
写入 → 工具构建交易，将其冻结以供离线签名，并返回 base64 字节及人类可读的摘要。你可以先检查交易（hedera_decode_transaction），然后自行签名并提交。
唯一可选的环境变量是 HEDERA_OPERATOR_ID——一个账户 ID，构建交易时用作默认付款方／金库。绝不是密钥。

这与 goat-network-mcp 的安全理念一致：可在任何地方安全运行，也可放心交给自主 Agent 使用。

已发布至 npm 和 MCP Registry，名称为 io.github.ExpertVagabond/hedera-mcp。

安装

使用 npx 直接运行（无需克隆）：

npx @purplesquirrel/hedera-mcp

或从源代码运行：

npm install
npm run build

配置（Claude Desktop／Claude Code）

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

环境变量	默认值	说明
`HEDERA_NETWORK`	`testnet`	`mainnet` \| `testnet` \| `previewnet`
`HEDERA_OPERATOR_ID`	(未设置)	可选的默认付款方／金库账户 ID（不是密钥）
`HEDERA_MIRROR_URL`	按网络而定	覆盖 Mirror Node REST 基础 URL（例如私有节点／HGraph 节点）

仅构建工作流

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

签名前检查所有内容：

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

工具目录（79）

账户（8）： create_account · transfer_hbar · update_account · delete_account · approve_hbar_allowance · get_account_info · get_account_balance · get_account_nfts

代币 / 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

共识 / HCS（6）： create_topic · submit_message · update_topic · delete_topic · get_topic_info · get_topic_messages

智能合约 / EVM（6）： deploy_contract · execute_contract · update_contract · delete_contract · query_contract · get_contract_info — execute_contract 和 query_contract 支持 ABI（传入 { abi, functionName, args }；自动编码 calldata 并解码结果）

文件（4）： create_file · append_file · update_file · delete_file

计划（4）： create_schedule · sign_schedule · delete_schedule · get_schedule_info

网络 / 实用工具（7）： prng · get_transaction · get_network_nodes · get_exchange_rate · get_network_supply · get_network_fees · decode_transaction

分析（Mirror Node 读取，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

资源（4）

除了工具外，该服务还提供可通过 URI 寻址、无需密钥的 MCP 资源，供 Agent 读取：

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

示例与学习

examples/TUTORIAL.md — 用 5 个提示词在 Hedera 上构建应用（从认证到发布的学习路径）
examples/agent-demo.md — 接入 Claude Desktop 并通过提问构建；运行 node examples/agent-sim.mjs 可打印可复现的 Agent 交互记录
examples/scenarios/ — 独特用例，每个都可运行并通过 Mirror Node 验证：HCS 公证、AI Agent 审计跟踪、Agent 间支付、自动征税代币

验证

npm run lint / npm run build — 使用 @hashgraph/sdk 2.81.0 检查通过
node test-battle.mjs — 自动发现测试套件中 72/73 项通过（1 项跳过：query_contract 需要已知 ABI，已单独验证）→ 73 个工具全部通过验证（MPP 前；包含 MPP 收费工具时为 79 个）
node test-live.mjs — 在测试网上执行了 10/10 条写入路径，并通过 Mirror Node 验证
node test-battle-live.mjs — 战斗模式：在测试网上对两个账户执行了 31/31 项操作（完整代币生命周期，包括冻结/KYC/暂停/清除、NFT、主题、文件、需要第二个签名者的定时转账、PRNG），并通过 Mirror Node 验证。改用 ED25519 操作员签名后重新运行：仍为 31/31 项通过——非 EVM 工具与密钥类型无关（服务不持有密钥；根据 Hedera 的 EVM 别名规则，EVM 工具本身需要 ECDSA）
node test-contract.mjs — 端到端编译 → 部署 → 执行 → 读取真实 Solidity 合约（store(42) → retrieve() = 42），确认完整 EVM 路径和 query_contract
node test-contract-abi.mjs — 支持 ABI 的 query_contract：输入原始 ABI 后，会自动进行编码/解码——answer() → 73（uint），title() → "hedera-mcp"（string），ping() → 73（pure）
node test-edge-cases.mjs — 在测试网上验证了 12/12 条边缘路径，这些路径在常规成功路径测试套件中会被遗漏：通过创建和追加上传大文件（超过一个交易块）；HCS 消息超过 1024 B，自动拆分到 2 条镜像条目中（重新组装后为 1200 B）；包含 10% 版税和 1ℏ 备用自定义费用的 NFT 集合；委托授权支出（操作员授权 B → B 支付自己的费用并提取 200）；向新的 ED25519 别名转账 HBAR，自动创建账户；以及 decode_transaction 往返验证

开发

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)

实时执行验证

test-execute.mjs 证明仅构建的输出确实可用：MCP 服务会构建一笔未签名交易，测试框架使用来自 .env 的一次性测试网密钥对其签名并提交，然后通过 Mirror Node 独立确认结果。整个过程中，服务始终只负责构建——只有测试框架会接触密钥。

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

在 portal.hedera.com 免费获取测试网账户。

基于 @hashgraph/sdk 和 @modelcontextprotocol/sdk 构建。

发布

更新 package.json、server.json（顶层的 version 和 packages[0].version）以及 src/index.ts 中的版本号；更新 CHANGELOG.md；然后发布到 npm 和 MCP Registry。

npm run build
npm publish --access public

接着同步 MCP Registry。请从 /tmp 运行 mcp-publisher，不要在项目目录中运行——在此环境中，项目所在卷不允许发布器持久化其 OAuth 令牌（operation not permitted），这会导致发布步骤悄然失败。将 server.json 复制到可写的临时目录即可绕过此问题：

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

确认这三个渠道均已同步：

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