chia-mcp

chia-mcp

一个 Model Context Protocol (MCP) 服务，提供 36 个工具，用于查询 Chia 区块链（启用 push_tx 和本地节点选项后最多可达 38 个）。使用由 Coinset 托管的节点，无需本地 Chia 节点。

快速开始

Claude Desktop

将以下内容添加到配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chia": {
      "command": "npx",
      "args": ["-y", "chia-mcp"]
    }
  }
}

Claude Code

claude mcp add chia -- npx -y chia-mcp
claude mcp add chia --env CHIA_NETWORK=testnet11 -- npx -y chia-mcp

Cursor

将以下内容添加到项目中的 .cursor/mcp.json，或添加到全局配置文件 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "chia": {
      "command": "npx",
      "args": ["-y", "chia-mcp"]
    }
  }
}

VS Code

将以下内容添加到用户设置（JSON）或 .vscode/mcp.json：

{
  "mcp": {
    "servers": {
      "chia": {
        "command": "npx",
        "args": ["-y", "chia-mcp"]
      }
    }
  }
}

测试网

将 CHIA_NETWORK 设为 testnet11，以使用测试网：

{
  "mcpServers": {
    "chia": {
      "command": "npx",
      "args": ["-y", "chia-mcp"],
      "env": {
        "CHIA_NETWORK": "testnet11"
      }
    }
  }
}

环境变量

变量	默认值	描述
CHIA_NETWORK	mainnet	要连接的网络：mainnet 或 testnet11
CHIA_FULL_NODE_URL	(根据网络自动设置)	覆盖全节点 RPC 端点 URL（例如，https://api.coinset.org 或你自己的节点）。本地 Chia 节点需要 mTLS 客户端证书；由于 chia-mcp 不直接支持客户端证书，请使用可终止 mTLS 的反向代理。
CHIA_MCP_ENABLE_PUSH_TX	(未设置)	设为 1 或 true 以启用 push_tx 工具（出于安全考虑，默认禁用）

可用工具

区块链状态

• get_blockchain_state — 当前链状态：峰值高度、同步状态、难度、子时隙迭代次数、内存池大小、网络空间估算值。
• get_network_info — 网络名称和地址前缀（xch/txch）。
• get_routes — 列出节点上所有可用的 RPC 端点（仅适用于非 Coinset 节点）。

区块

• get_block — 根据区块头哈希获取完整区块（交易、证明、奖励）。
• get_block_record — 根据区块头哈希获取区块记录（比完整区块更精简）。
• get_block_record_by_height — 获取指定高度的区块记录元数据（比完整区块更精简）。
• get_block_records — 获取高度范围 [start, end) 内的区块记录。
• get_blocks — 获取高度范围 [start, end) 内的完整区块。
• get_block_spends — 根据区块头哈希获取区块中的所有 Coin 花费。
• get_block_spends_with_conditions — 根据区块头哈希获取带有已解析 CLVM 条件的 Coin 花费。
• get_additions_and_removals — 获取区块中创建和花费的所有 Coin。
• get_unfinished_block_headers — 获取未完成的区块头（正在生成的区块）。
• get_block_count_metrics — 区块计数指标（紧凑／非紧凑区块数量）。

Coin

• get_coin_record_by_name — 根据 ID 获取单个 Coin（parent+puzzle_hash+amount 的 sha256）。
• get_coin_records_by_names — 根据 ID 获取多个 Coin（批量查询）。
• get_coin_records_by_puzzle_hash — 获取锁定到某个 puzzle hash 的 Coin，可选按已花费状态／高度筛选。
• get_coin_records_by_puzzle_hashes — 获取锁定到多个 puzzle hash 的 Coin（批量查询）。
• get_coin_records_by_hint — 获取带有某个提示的 Coin（常见于 CAT/NFT 交易）。
• get_coin_records_by_hints — 获取带有多个提示的 Coin（批量查询）。
• get_coin_records_by_parent_ids — 获取由指定父 Coin 创建的 Coin（追踪来源链）。
• get_puzzle_and_solution — 获取指定高度上已花费 Coin 的 CLVM puzzle 和 solution。
• get_puzzle_and_solution_with_conditions — 获取已花费 Coin 的 puzzle、solution 及已解析的 CLVM 条件。
• get_memos_by_coin_name — 获取与某个 Coin 关联的备忘录／消息。

内存池

• get_all_mempool_tx_ids — 列出所有待处理交易 ID。
• get_all_mempool_items — 获取内存池中所有条目的完整详情（内容可能很大）。
• get_mempool_item_by_tx_id — 根据交易 ID 获取单个内存池条目。
• get_mempool_items_by_coin_name — 获取引用特定 Coin 的内存池条目。
• get_fee_estimate — 获取不同目标确认时间的手续费估算值。

交易

• push_tx — 将已签名的支出包提交到内存池。
• get_aggsig_additional_data — 用于签名验证的 AGG_SIG 附加数据。

网络

• get_network_space — 估算两个区块之间的网络总空间。

组合查询（更高级的查询，涉及多个 RPC）

• get_address_summary — 提供地址或 puzzle hash 的完整余额摘要。遍历所有未花费的币，以计算准确的总额，并提供 complete 标志。这是检查余额的正确方式。
• decode_offer — 将 Chia 报价字符串（offer1...）解码为结构化摘要：币支出、金额、币 ID、puzzle 大小和签名状态。使用官方 chia-wallet-sdk 进行正确解析。
• trace_coin_lineage — 将币的祖先追溯到其来源（coinbase）。沿父链接最多追溯 max_depth 跳。
• summarize_block — 区块中所有币流动的简明摘要：数量、总额、最大流动，以及按 puzzle hash 统计的净流量。比原始的 get_additions_and_removals（可能超过 1 MB）实用得多。

实用工具（本地计算，无需 RPC）

• address_encode — 将 puzzle hash 转换为 bech32m Chia 地址（xch1.../txch1...）。
• address_decode — 将 bech32m Chia 地址解码回其 puzzle hash。
• coin_id — 根据 parent_coin_id + puzzle_hash + amount 计算币 ID。

工具示例

快速参考，展示最常用工具的输入 → 输出格式。

get_blockchain_state

Input:  {} (no parameters)
Output: { peak_height: 9470000, sync: { synced: true }, difficulty: 2528, space: "33501849665552384", mempool_size: 3, ... }

get_coin_record_by_name

Input:  { name: "0xabc123..." }
Output: { coin: { parent_coin_info: "0x...", puzzle_hash: "0x...", amount: 1750000000000 }, confirmed_block_index: 5000000, spent_block_index: 5000042, coinbase: false, timestamp: 1700000000 }

get_coin_records_by_puzzle_hash

Input:  { puzzle_hash: "0xabc123...", include_spent_coins: false }
Output: [ { coin: { ... }, confirmed_block_index: ..., spent_block_index: 0 }, ... ]
Note:   Response truncated at 50KB. For complete balance, use get_address_summary instead.

get_address_summary

Input:  { address: "xch1abc123..." }
Output: { total_balance_mojos: "1750000000000", total_balance_xch: "1.75", coin_count: 3, complete: true, oldest_coin_height: 4500000, newest_coin_height: 9400000 }
Note:   Pages through ALL unspent coins. The `complete` flag indicates whether the full balance was reached.

trace_coin_lineage

Input:  { coin_id: "0xabc123...", max_depth: 10 }
Output: { lineage: [ { coin_id: "0x...", parent: "0x...", amount: 1750000000000, height: 5000042 }, ... ], depth_reached: 5, reached_coinbase: true }

summarize_block

Input:  { header_hash: "0xabc123..." }
Output: { height: 5000042, is_transaction_block: true, num_additions: 12, num_removals: 6, total_amount_created: "3500000000000", total_amount_spent: "3500000000000", top_movements: [ ... ] }
Note:   Much smaller than raw get_additions_and_removals (which can be 1+ MB).

decode_offer

Input:  { offer: "offer1..." }
Output: { valid: true, summary: { offered: { xch: "1.0" }, requested: { "asset_id_abc...": 100 } }, coin_spends: 3, has_signature: true }

address_encode

Input:  { puzzle_hash: "0xabc123...", prefix: "xch" }
Output: { address: "xch1abc123..." }
Note:   Local computation — no RPC call.

address_decode

Input:  { address: "xch1abc123..." }
Output: { puzzle_hash: "0xabc123..." }
Note:   Local computation — no RPC call.

coin_id

Input:  { parent_coin_info: "0x...", puzzle_hash: "0x...", amount: 1750000000000 }
Output: { coin_id: "0xabc123..." }
Note:   SHA256(parent + puzzle_hash + amount). Accepts string amounts for values > Number.MAX_SAFE_INTEGER.

资源

网络状态（实时）

• chia://network/mainnet — Mainnet 连接信息和实时区块链状态。
• chia://network/testnet11 — Testnet11 连接信息和实时区块链状态。

指南（内嵌文档）

• chia://guide/coin-model — Chia 的币/UTXO 模型、支出包、代币标准，以及常见的大模型错误。
• chia://guide/rpc-quickstart — 常用 RPC 调用、curl 示例和 Coinset 端点。
• chia://guide/recipes — 余额检查、交易追踪、CAT 检测的分步指南，以及故障模式。

工作原理

此服务使用 Coinset 托管的端点封装了 Chia 全节点 RPC API：

• Mainnet： https://api.coinset.org/<method>
• Testnet11： https://testnet11.api.coinset.org/<method>

所有 RPC 调用都是带 JSON 正文的简单 HTTP POST 请求。无需身份验证。

Coinset 托管节点与本地节点

大多数工具适用于任何 Chia 全节点（由 Coinset 托管的节点或你自己的节点）。有 3 个工具是 Coinset 扩展——它们不存在于 chia-blockchain 的全节点 RPC API 中，因此对本地节点或模拟器调用时会返回 HTTP 404：

工具	Coinset	本地节点 / 模拟器
get_puzzle_and_solution_with_conditions	✅	❌ — 使用 get_puzzle_and_solution + 本地 CLVM 求值
get_memos_by_coin_name	✅	❌
get_coin_records_by_hints	✅	❌ — 仅存在单数形式的 get_coin_records_by_hint

模拟器兼容性： 针对 Coinset 扩展端点编写的代码无法用于模拟器或本地节点。模拟器（chia dev sim）和标准 chia-blockchain 节点支持相同的标准 RPC 接口。为了获得最佳兼容性，请使用标准 RPC 针对模拟器进行开发；生产环境查询时可使用 Coinset 扩展以提高便利性。

共享 RPC： get_network_info 和 get_aggsig_additional_data 是所有 Chia 服务上均可用的共享 RPC 端点（并非全节点专用）。它们同时适用于 Coinset 和本地节点。

有意省略的 RPC： 有 3 个上游全节点 RPC 未作为工具公开：get_constants（静态数据，通过 constants.json 提供更合适）、get_recent_signage_point_or_eos（对 Agent 用处不大的内部共识细节）和 create_block_generator（timelord/farmer 内部接口）。其他所有全节点 RPC 均已公开。

提示词

此服务提供 9 个提示词，为常见 Chia 任务编码了工具调用顺序和故障模式：

提示词	说明
network_status	检查 Chia 网络的当前状态：峰值高度、同步状态、难度、内存池。
address_balance	使用 get_address_summary 准确检查 Chia 地址的 XCH 余额。
coin_lookup	根据 coin ID 查找特定 coin 并查看其详细信息。
trace_lineage	追踪 coin 的父链，以了解资金来源。
block_summary	汇总区块内容：交易数量、转移价值、主要地址。
transaction_status	检查交易是已确认、仍在内存池中，还是已丢弃。
offer_safety	评估 Chia offer 是否可以安全接受（隐藏的花费、资产验证、到期时间）。
token_verification	通过对照可信注册表检查资产 ID，验证代币（CAT）是否合法。
fee_selection	根据当前网络状况，确定 Chia 交易的合适手续费。

已知限制

• Coinset 托管节点上无法使用 get_routes — 返回 HTTP 404。这是 Coinset 的限制，并非此服务中的错误。连接到本地 Chia 节点时，该工具可以正常使用。
• 大整数精度 — 所有已知的 uint64 字段（amount、space、timestamp、weight、total_iters、sub_slot_iters、required_iters、fee、cost、mempool_cost、mempool_max_total_cost、mempool_min_fee_per_cost）在响应中都会以带引号的字符串形式返回；任何不带引号且 ≥16 位的整数也会加上引号，以防 JavaScript 精度丢失。对于超过 Number.MAX_SAFE_INTEGER 的值，coin_id 工具也接受字符串形式的金额。
• 响应截断 — 大于 50 KB 的响应会自动截断。请使用更窄的查询参数（较小的区块高度范围、指定 coin ID 而不是批量查询），以避免响应被截断。
• push_tx 遇到 429 时不会重试 — 当 RPC 返回 HTTP 429（速率限制）时，除 push_tx 外的所有方法都会在延迟后重试一次。为防止意外重新广播交易，push_tx 不会重试。
• network_verified 生命周期 — 每个响应封套中的 network_verified 字段在首次成功探测 RPC 前为 "pending"，之后会变为 true（匹配）或 false（不匹配）。如果无法访问配置的节点，该字段会变为 false（探测失败）。
• npm audit 安全公告 — MCP SDK 的传递依赖可能会触发 npm audit 安全公告。在 stdio-transport 配置中，这些依赖无法被访问（不会暴露 HTTP 服务）。它们不会影响标准 chia-mcp 部署的安全状况。

从源代码安装

用于开发或贡献：

git clone https://github.com/Chia-Network/chia-mcp.git
cd chia-mcp
npm install
npm run build

然后，在 MCP 客户端配置中使用 node /path/to/chia-mcp/dist/index.js，而不是 npx -y chia-mcp。例如，在 Claude Desktop 中：

{
  "mcpServers": {
    "chia": {
      "command": "node",
      "args": ["/path/to/chia-mcp/dist/index.js"]
    }
  }
}

开发

npm test                # Run test suite
npm run dev             # Watch mode (recompiles on changes)
node dist/index.js      # Run the server directly

许可证

Apache-2.0