quai-mcp-server

一个 MCP（模型上下文协议）服务器，向 Claude Desktop 和 Claude Code 等 AI 客户端暴露 Quai 网络链数据和只读交互工具。使用官方的 @modelcontextprotocol/sdk 和 quais（Quai 的类 ethers SDK）构建。

什么是 Quai 网络（通俗解释）

Quai 是一个工作量证明、兼容 EVM 的第 1 层网络，通过分片进行扩展：它不是由一条链完成所有工作，而是分成许多按层级排列的链。

                Prime chain (1)
               /      |       \
        Region      Region      Region      <- "Cyprus", "Paxos", "Hydra"
       /  |  \      /  |  \     /  |  \
     Zone Zone Zone  ...              9 Zone chains total

• Prime 是唯一的顶层链。每个矿工都挖 Prime；它负责整个网络的状态结算，但不直接处理用户交易。

• Region 链（目前为 Cyprus、Paxos、Hydra）位于 Prime 之下，聚合其 Zone。

• Zone 链（Cyprus1/2/3、Paxos1/2/3、Hydra1/2/3——目前 9 个，随着网络增长可以增加）是实际 EVM 所在之处：用户交易、合约、余额，一切。

与将安全性和数据一起分割的分片设计不同，Quai 在整个层级中保持安全性统一，而只分割数据/吞吐量——Prime 和 Region 链与其下方的 Zone 链进行合并挖矿。

对工具来说最重要的部分：每个 Quai 地址都是位置感知的。地址自身的字节编码了它所在的单个 Zone（以及它是在 QUAI 账本上（类似以太坊的账户制）还是在 Qi 账本上（类似比特币的 UTXO 制））。Cyprus1 上的地址只存在于 Cyprus1——你不能向 Paxos2 询问它。这就是为什么下面几个工具要么自动为你解析 zone，要么要求你明确指定一个。

Related MCP server: Kirha MCP Gateway

工具

只读

这些工具都不能转移资金、签署任何内容或更改链上状态。

钱包（托管式：加密、命名、密码保护）

一旦你创建或导入钱包，此服务器就会代表你持有密钥——从狭义、本地的意义上说，它是托管式的，就像 geth 密钥库或 MetaMask 的本地保险库一样。它不作为他人资金的主机服务运行；所有内容都存在于运行服务器的机器上的一个目录中，并使用只有你知道的密码加密。

加密方式：每个钱包都是标准 Web3 秘密存储（V3 密钥库） 格式中的私钥——与 geth 和 MetaMask 使用的格式相同——通过 quais 的 encryptKeystoreJson。具体来说：密码使用 scrypt 进行拉伸（N=2^17, r=8, p=1，标准的“昂贵”成本参数——这故意使每次密码猜测变慢），私钥使用 AES-128-CTR 加密，并且对密文进行 MAC 校验，在从中派生任何密钥材料之前检测错误密码（或篡改的文件）。这是一个经过充分审查、广泛部署的方案；这里没有自定义加密。

钱包存放位置：默认在 ~/.quai-mcp-server/wallets/（可用 QUAI_WALLET_DIR 覆盖）——QUAI 钱包为 <name>.json，Qi 钱包为 <name>.qi.json。目录创建为 0700，每个密钥库文件为 0600（仅所有者读/写，在非 POSIX 平台上尽力而为）——在创建后显式强制执行，而不仅仅依赖进程 umask。两种情况下地址都以明文存储（这是公开信息；这就是 list_wallets 和 QUAI 侧预览无需密码即可工作的原因），但私钥（或 Qi 的助记词）永远不会被任何工具以明文写入、记录或返回。

命名：一个名称最多标识一个 QUAI 钱包 和 最多一个 Qi 钱包——它们是独立的密钥库（不同的文件、不同的秘密、完全无关的密钥材料），恰好共享一个标签。你不能创建两个同名的 QUAI 钱包（或两个 Qi 钱包），但将 QUAI 钱包的名称用于 Qi 钱包正是 create_wallet 配对的工作方式，而 create_qi_wallet/import_qi_wallet 出于同样的原因故意允许这样做。

Qi 钱包在底层是 HD 钱包，但此服务器只存储助记词——从不存储派生的地址树或任何 UTXO/扫描状态。create_qi_wallet/import_qi_wallet 通过与 QUAI 侧完全相同的 encryptKeystoreJson 调用加密 {address, privateKey, mnemonic}（那里的 address/privateKey 字段只是钱包的第一个派生地址，存在是为了使文件成为正常、有效的 V3 密钥库）；有意义的秘密是助记词。之后的每个操作（get_qi_balance、convert_qi_to_quai）都会从该助记词重新构建一个新的 QiHDWallet，并按需重新派生相同的接收地址——这是确定性的，因为固定账户/zone 的 HD 派生总是产生相同的地址。这已直接验证：导出钱包的助记词并以不同名称重新导入，重现了相同的地址。权衡是，每个 Qi 操作都从头重新派生，而不是读取缓存，这更容易推理，也不会偏离助记词实际暗示的内容，代价是比 QUAI 侧更频繁地需要密码（见下文）。

为什么 Qi 需要更频繁地输入密码：QUAI 的 get_balance 直接从链上读取公开账户余额——不需要任何秘密。Qi 没有这样的机制："余额"是归属于地址的未花费交易输出（UTXO）之和，而这些地址只能由钱包的助记词推导出来，因此要计算余额就必须先重建钱包。这就是为什么 get_qi_balance 需要密码（而 QUAI 的 get_balance 不需要），也是为什么 convert_qi_to_quai 的预览步骤可以给出兑换率报价，但无法确认你实际是否有足够的 Qi 可花费——这个检查只有在密码到达确认步骤时才会进行。

密码规则：最少 8 个字符，在任何内容被加密之前进行检查。对错误密码尝试没有单独的速率限制——scrypt 的成本参数已经使每次猜测在计算上代价高昂，这是此类本地密钥库的标准防御手段。

send_transaction、convert_qi_to_quai 和 send_qi 的确认流程：这三个操作都始终需要两次调用，且只有第二次需要密码。

1. 使用目的地和金额调用（send_transaction 用 walletName/to/amount；send_qi 用 walletName/recipientPaymentCode/amount/destinationZone；convert_qi_to_quai 用类似 to 的形式）——此时还不需要密码。不会广播任何内容。你会得到一个预览——已解析的区域、存在时的估算值（发送时的 gas，转换时的兑换金额；send_qi 没有估算值，因为它是 1:1 转账），以及一个有效期为 2 分钟的 confirmationToken。

2. 使用相同的参数再次调用，并加上 confirm: true、那个 confirmationToken 以及钱包的 password。只有到这时密钥/助记词才会被解密，交易才会被实际签名并发送。

令牌是一次性的，并且绑定到预览时的确切参数——如果任何内容发生变化、令牌已过期或已被使用，步骤 2 会以清晰的错误信息失败，你需要重新预览。无论 MCP 客户端本身是否有工具审批界面，这个机制都以相同方式工作，因此它是一个真正的门禁，而不是依赖客户端来提供。错误密码会干净地失败（Incorrect password for wallet "..."），不会泄露令牌/参数在其他方面是否有效。

有意不提供 export_wallet/"显示私钥或助记词"工具——一旦秘密进入存储，通过此服务器离开的唯一方式就是用其签名。

QUAI ↔ Qi 转换（"兑换"）：Quai 在其两个账本之间有一种原生的、协议级别的转换——QUAI（基于账户）和 Qi（基于 UTXO，类似比特币）——使用链上汇率，而非第三方 DEX。get_conversion_rate 可以双向报价，无需钱包。两个执行方向现在都已实现：

• QUAI → Qi：只是向 Qi 账本地址（例如来自 create_qi_wallet 的地址）发起一次普通的 send_transaction。该工具会自动检测到这一点（预览中 isConversion: true），并在常规的 gas/余额信息旁边显示估算的 Qi 接收量。

• Qi → QUAI：convert_qi_to_quai，底层使用 quais 的 QiHDWallet.convertToQuai，遵循与 send_transaction 相同的预览/确认/密码模式。

Qi → Qi 发送：Qi 钱包不会直接向彼此的地址发送。相反，每个 Qi 钱包都有一个可复用的 BIP-47 支付码（get_qi_payment_code）——像分享地址一样分享它，但每次支付都会从中推导出一个全新的一次性地址，以保护隐私。要发送时，发送方与接收方的支付码"打开一个通道"（send_qi 会自动完成）——这只是两个支付码之间的纯本地 ECDH，确定且可重现，不涉及链上操作或持久化状态。问题出在接收端：那些成对推导出的地址不属于钱包正常的确定性地址序列，因此除非你告诉它去查找，否则没有任何东西会找到以这种方式发送的资金。具体来说：在有人通过支付码向你的 Qi 钱包付款后，将他们的支付码传入 get_qi_balance 的 counterpartyPaymentCodes——它会打开同一个通道并将其计入余额。没有任何通知机制（链上或其他方式）告诉接收方有一笔支付码付款已到达；双方必须已经通过带外方式知道彼此，就像你在检查余额之前需要知道一个地址一样。send_qi 还支持跨区域发送（一个与发送方自身区域不同的 destinationZone），方式与 send_transaction 的 ETX 和 QiHDWallet 自身的区域模型相同。

一个已知的粗糙边缘：send_qi 的预览步骤不会预先验证支付码的格式（没有导出的验证器可以对照检查），因此格式错误的支付码会正常预览，只在确认时才会失败——安全地失败（不会发送任何内容，资金没有风险），只是比理想情况晚了一些。

尚未实现：deploy_contract、request_faucet。

关于此处测试内容的诚实说明（已更新）：完整的 send_qi / 支付码流程已使用两个真实钱包在主网上进行了实时验证——生成了一个真实、格式正确的 BIP-47 支付码（PM8T...）并确认在多次调用间是确定性的；预览正确区分了跨区域与同区域；对空钱包的确认以真实的 SDK 错误（No Qi available in zone）失败而非崩溃；get_qi_balance 正确地将无效的对手方支付码隔离到 rejectedPaymentCodes 中，而不会使整个调用失败。仍未验证的内容，原因与本文档其他部分相同：一笔在两个有资金的钱包之间实际完成的支付码发送，因为这需要真实的 Qi，且未经要求不会执行。

关于此处测试内容的诚实说明：以上所有内容都在实时主网上进行了验证，包括确定性检查（导出 Qi 钱包的助记词并以不同名称重新导入，重现了相同的地址）和真实错误路径（错误密码、QUAI gas 不足，以及一个真实的 QiHDWallet 错误——No Qi available in zone——在尝试从空 Qi 钱包转换时）。尚未验证的是 convert_qi_to_quai 或 QUAI→Qi 转换在持有真实资金的钱包上实际完成，因为这需要花费真金白银，且未经要求不会执行。

安装

npm install
npm run build

或者发布后无需安装直接运行：

npx quai-mcp-server

要求

• Node.js 18+

配置（环境变量）

全部可选——合理的默认值指向 Quai 主网。

每个工具还接受每次调用的 network 参数（"mainnet" 或 "testnet"），因此客户端无需重启服务器即可查询任一网络。

关于密钥：参见上文"钱包"。密钥仅在需要它们的 create_wallet/import_wallet/send_transaction 调用期间以明文形式存在于内存中——绝不在磁盘上，绝不记录日志。像对待任何其他本地秘密存储一样对待 QUAI_WALLET_DIR（以及运行此服务器的任何机器）：任何对该目录具有文件系统访问权限且拥有足够计算能力来暴力破解弱密码的人，最终都能解密钱包，与本地 geth 密钥库或 MetaMask 保险库相同。

注册到 Claude Desktop

将此添加到你的 Claude Desktop MCP 配置中（claude_desktop_config.json——在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"]
    }
  }
}

或者，如果你已克隆并在本地构建了此仓库，而不是使用已发布的包：

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

要默认指向测试网，请添加一个 env 块：

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"],
      "env": {
        "QUAI_TESTNET_RPC_URL": "https://orchard.rpc.quai.network"
      }
    }
  }
}

（然后在单个工具调用中传入 "network": "testnet"——环境变量设置的是端点，而不是每次调用的默认网络）。

注册到 Claude Code

claude mcp add quai -- npx quai-mcp-server

或者，对于本地构建：

claude mcp add quai -- node /absolute/path/to/quai-mcp-server/dist/index.js

开发

npm run dev     # tsc --watch
npm run build   # one-shot build to dist/
npm start        # run the built server directly (stdio) -- mainly useful for manual smoke tests

服务器在 v1 中仅通过 stdio 进行 MCP 通信；没有 HTTP 传输。

设计说明

• 通过原始 RPC 使用 quais：每个工具都通过 quais SDK 的 JsonRpcProvider、Contract 和地址工具，而不是手写的 eth_/quai_ JSON-RPC 调用，因此区域解析、响应格式和错误形态与 Quai 生态系统的其余部分保持一致。

• 一个提供者，多个区域：指向基础网关 URL（例如 https://rpc.quai.network）的单个 JsonRpcProvider 会自动从 Prime 链发现活动区域，并将每个调用路由到正确的区域——大多数工具从不构造按区域的 URL。

• 托管，用标准工具而非自定义加密实现：钱包使用 quais 对以太坊 V3 密钥库格式（scrypt + AES-128-CTR + MAC）的实现来存储——与 geth 和 MetaMask 使用的经过充分审查的方案相同——而不是任何手写方案。完整模型参见上文"钱包"。

• 错误是文本，不是堆栈跟踪：RPC/合约错误会被捕获并重写为简短、具体的消息（例如 "Contract call reverted: ..."、"Insufficient funds: ..."、"Incorrect password for wallet..."、"not a validly checksummed Quai address"），而不是向模型泄露原始异常对象。

• 确认是真正的门禁，而不仅仅是客户端提示：写入工具被标注为 readOnlyHint: false（发送操作还有 destructiveHint: true），因此带有自己的审批界面的 MCP 客户端会显示一个，但 send_transaction 另外在服务端强制执行自己的预览 → 令牌 → 密码握手（src/confirmations.ts 负责令牌，src/walletStore.ts + decryptKeystoreJson 负责密码），因此从完全没有审批界面的客户端调用它也是安全的。

• 密码只在最后时刻需要一次：预览发送时，直接从钱包密钥库文件的未加密部分解析钱包地址，并使用 VoidSigner（一个可以估算 gas 但不能签名的 quais 签名者）来估算成本——无需解密，无需密码。只有最终的 confirm: true 调用才会解密密钥，且仅在该次调用期间。

• ETX 不是独立的代码路径：向不同区域的地址发送与同区域发送使用完全相同的 send_transaction 调用——一旦签名交易到达发送方所在区域，Quai 网络会透明地处理跨区域路由（作为外部交易）。该工具只是检测并报告所涉及的区域，以便调用者知道会发生什么。

• Qi 钱包在调用之间有意保持无状态：create_qi_wallet/import_qi_wallet 只加密助记词。get_qi_balance 和 convert_qi_to_quai 每次调用都从头重建 QiHDWallet 并重新推导其地址（src/qiWallet.ts），而不是读取任何缓存的地址/UTXO 状态——因为根本没有可读的状态。这以一点性能为代价（每次 Qi 操作都重新推导和重新查询，而不是命中缓存），换来了更简单、更难出错的安全故事：唯一处于静止状态的只有那个最重要的秘密。