Phoenixd MCP Server

Phoenixd MCP 服务

将 phoenixd 比特币闪电网络钱包连接到你的大模型。

此 MCP 服务使用 MCP TypeScript SDK 和 Phoenixd API。

前提条件

你需要一个正在运行的 phoenixd 节点。Phoenixd 首次运行时会生成一个 HTTP 密码，并将其写入 ~/.phoenix/phoenix.conf：

http-password=your_generated_password

在下方配置中，将该值用于 HTTP_PASSWORD。

需要 Node.js >= 18。

配置

与 Claude Desktop 搭配使用

将以下内容添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "phoenixd-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "phoenixd-mcp-server"
      ],
      "env": {
        "HTTP_PROTOCOL": "http",
        "HTTP_HOST": "127.0.0.1",
        "HTTP_PORT": "9740",
        "HTTP_PASSWORD": "<your_password_from_phoenix.conf>"
      }
    }
  }
}

远程节点（VPS / HTTPS）

如果 phoenixd 在反向代理和 TLS 后的远程服务上运行：

{
  "mcpServers": {
    "phoenixd-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "phoenixd-mcp-server"
      ],
      "env": {
        "HTTP_PROTOCOL": "https",
        "HTTP_HOST": "your.server.com",
        "HTTP_PORT": "9740",
        "HTTP_PASSWORD": "<your_password_from_phoenix.conf>"
      }
    }
  }
}

工具

支付

• create-invoice

  • 创建一张指定金额和描述的 bolt11 发票。
  • 输入：
    • description（字符串，可选）：发票描述（最多 128 个字符）。必须提供 description 或 descriptionHash。
    • descriptionHash（字符串，可选）：描述的 SHA256 哈希值。使用此参数代替 description。
    • amountSat（数字，可选）：发票请求的金额，单位为 satoshi。若未设置，发票可按任意金额支付。
    • expirySeconds（数字，可选）：发票的有效期，单位为秒，默认值为 3600（1 小时）。
    • externalId（字符串，可选）：用于将发票关联到外部系统的自定义标识符。
    • webhookUrl（字符串，可选）：发票支付后，phoenixd 会向此 URL 发送 POST 请求。载荷为包含支付详情的 JSON 对象，具体定义见 Phoenixd API 文档。

• create-offer

  • 创建一个 bolt12 offer。
  • 输入：
    • description（字符串）：offer 的描述。
    • amountSat（数字，可选）：offer 请求的金额，单位为 satoshi。
    • expirySeconds（数字，可选）：offer 的有效期，单位为秒。

• pay-invoice

  • 支付一张 bolt11 发票。
  • 输入：
    • invoice（字符串）：要支付的 bolt11 发票。
    • amountSat（数字，可选）：要支付的金额，单位为 satoshi（仅适用于零金额发票）。不能与 sendAll 同时使用。
    • sendAll（布尔值，可选）：若为 true，则清空钱包。不能与 amountSat 同时使用。
    • externalId（字符串，可选）：用于将支付关联到外部系统的自定义标识符。

• pay-offer

  • 支付一个 bolt12 offer。
  • 输入：
    • offer（字符串）：要支付的 bolt12 offer。
    • amountSat（数字，可选）：要支付的金额，单位为 satoshi。不能与 sendAll 同时使用。
    • sendAll（布尔值，可选）：若为 true，则清空钱包。不能与 amountSat 同时使用。
    • message（字符串，可选）：给收款人的消息。
    • externalId（字符串，可选）：用于将支付关联到外部系统的自定义标识符。

• pay-lightning-address

  • 支付一个 Lightning Address。
  • 输入：
    • address（字符串）：要支付的 Lightning Address（例如：[email protected]）。
    • amountSat（数字，可选）：要支付的金额，单位为 satoshi。不能与 sendAll 同时使用。
    • sendAll（布尔值，可选）：若为 true，则清空钱包。不能与 amountSat 同时使用。
    • message（字符串，可选）：随支付附上的可选消息。

• pay-on-chain

  • 发送一笔链上比特币支付。
  • 输入：
    • address（字符串）：接收资金的比特币地址。
    • amountSat（数字）：要发送的金额，单位为 satoshi。
    • feerateSatByte（数字，可选）：费率，单位为每字节 satoshi。

• bump-fee

  • 使用 CPFP 提高所有未确认链上交易的费率。返回子交易的 ID。
  • 输入：
    • feerateSatByte（数字）：新的费率，单位为每字节 satoshi。

• list-incoming-payments

  • 列出收到的付款（发票）。
  • 输入：
    • from (string, optional)：从纪元起算的开始时间戳，单位为毫秒，默认值为 0。
    • to (string, optional)：从纪元起算的结束时间戳，单位为毫秒，默认值为当前时间。
    • limit (number, optional)：每页的付款数量，默认值为 20。
    • offset (number, optional)：页面偏移量，默认值为 0。
    • all (boolean, optional)：同时返回未付款的发票，默认值为 false。
    • externalId (string, optional)：bolt11 发票的外部 ID。

• get-incoming-payment

  • 获取特定收到的付款（发票）的详情。
  • 输入：
    • paymentHash (string)：发票的付款哈希。

• list-outgoing-payments

  • 列出发出的付款。
  • 输入：
    • from (string, optional)：从纪元起算的开始时间戳，单位为毫秒，默认值为 0。
    • to (string, optional)：从纪元起算的结束时间戳，单位为毫秒，默认值为当前时间。
    • limit (number, optional)：每页的付款数量，默认值为 20。
    • offset (number, optional)：页面偏移量，默认值为 0。
    • externalId (string, optional)：付款的外部 ID。

• get-outgoing-payment

  • 获取特定发出的付款的详情。
  • 输入：
    • paymentHash (string)：发出的付款的付款哈希。

节点管理

• get-node-info

  • 获取节点信息。
  • 输入：无

• get-balance

  • 获取节点余额。
  • 输入：无

• list-channels

  • 列出节点通道。
  • 输入：无

• close-channel

  • 按 ID 关闭通道，将资金发送到链上指定地址，并使用指定的费率。
  • 输入：
    • channelId (string)：要关闭的通道 ID。
    • address (string)：用于接收资金的 Bitcoin 链上地址。
    • feerateSatByte (number)：每字节的手续费率，单位为聪。

• decode-invoice

  • 解码 bolt11 发票，输出金额的单位为毫聪。
  • 输入：
    • invoice (string)：要解码的 bolt11 发票。

• decode-offer

  • 解码 bolt12 offer，输出金额的单位为毫聪。
  • 输入：
    • offer (string)：要解码的 bolt12 offer。

故障排除

Authentication failed / 401 — 检查 HTTP_PASSWORD 是否与 ~/.phoenix/phoenix.conf 中的值一致。

Connection refused — Phoenixd 未运行，或正在不同的主机/端口上监听。使用 curl http://127.0.0.1:9740/getinfo -u :your_password 验证。

Node.js version error — 此软件包需要 Node.js >= 18。运行 node --version 进行检查。