Phoenixd MCP Server

Connect a phoenixd bitcoin lightning wallet to your LLM.

This MCP server uses MCP TypeScript SDK and Phoenixd API.

Prerequisites

You need a running phoenixd node. Phoenixd generates an HTTP password on first run and writes it to ~/.phoenix/phoenix.conf:

http-password=your_generated_password

Use that value for HTTP_PASSWORD in the configuration below.

Node.js >= 18 is required.

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json file:

{
  "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>"
      }
    }
  }
}

Remote node (VPS / HTTPS)

If phoenixd runs on a remote server behind a reverse proxy with 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>"
      }
    }
  }
}

Tools

Payments

• create-invoice

  • Create a bolt11 invoice with a specified amount and description.

  • Inputs:

    • description (string, optional): The description of the invoice (max. 128 characters). Either description or descriptionHash must be provided.

    • descriptionHash (string, optional): SHA256 hash of the description. Use instead of description.

    • amountSat (number, optional): The amount requested by the invoice, in satoshi. If not set, the invoice can be paid by any amount.

    • expirySeconds (number, optional): The invoice expiry in seconds, default 3600 (1 hour).

    • externalId (string, optional): A custom identifier to link the invoice to an external system.

    • webhookUrl (string, optional): A URL that phoenixd will POST to when this invoice is paid. The payload is a JSON object with the payment details as defined in the Phoenixd API docs.

• create-offer

  • Create a bolt12 offer.

  • Inputs:

    • description (string): The description of the offer.

    • amountSat (number, optional): The amount requested by the offer, in satoshi.

    • expirySeconds (number, optional): The offer expiry in seconds.

• pay-invoice

  • Pay a bolt11 invoice.

  • Inputs:

    • invoice (string): The bolt11 invoice to pay.

    • amountSat (number, optional): Amount to pay in satoshis (only for zero-amount invoices). Mutually exclusive with sendAll.

    • sendAll (boolean, optional): If true, empties the wallet. Mutually exclusive with amountSat.

    • externalId (string, optional): A custom identifier to link the payment to an external system.

• pay-offer

  • Pay a bolt12 offer.

  • Inputs:

    • offer (string): The bolt12 offer to pay.

    • amountSat (number, optional): Amount to pay in satoshis. Mutually exclusive with sendAll.

    • sendAll (boolean, optional): If true, empties the wallet. Mutually exclusive with amountSat.

    • message (string, optional): A message for the recipient.

    • externalId (string, optional): A custom identifier to link the payment to an external system.

• pay-lightning-address

  • Pay a Lightning Address.

  • Inputs:

    • address (string): The Lightning Address to pay (e.g., swamppawpaw18@phoenixwallet.me).

    • amountSat (number, optional): Amount to pay in satoshis. Mutually exclusive with sendAll.

    • sendAll (boolean, optional): If true, empties the wallet. Mutually exclusive with amountSat.

    • message (string, optional): Optional message to include with the payment.

• pay-on-chain

  • Send an on-chain Bitcoin payment.

  • Inputs:

    • address (string): The Bitcoin address to send funds to.

    • amountSat (number): Amount to send in satoshis.

    • feerateSatByte (number, optional): Fee rate in satoshis per byte.

• bump-fee

  • Bumps the fee rate of all unconfirmed on-chain transactions using CPFP. Returns the ID of the child transaction.

  • Inputs:

    • feerateSatByte (number): New fee rate in satoshis per byte.

• list-incoming-payments

  • List incoming payments (invoices).

  • Inputs:

    • from (string, optional): Start timestamp in millis from epoch, default 0.

    • to (string, optional): End timestamp in millis from epoch, default now.

    • limit (number, optional): Number of payments per page, default 20.

    • offset (number, optional): Page offset, default 0.

    • all (boolean, optional): Also return unpaid invoices, default false.

    • externalId (string, optional): External id of the bolt11 invoice.

• get-incoming-payment

  • Get details of a specific incoming payment (invoice).

  • Inputs:

    • paymentHash (string): The payment hash of the invoice.

• list-outgoing-payments

  • List outgoing payments.

  • Inputs:

    • from (string, optional): Start timestamp in millis from epoch, default 0.

    • to (string, optional): End timestamp in millis from epoch, default now.

    • limit (number, optional): Number of payments per page, default 20.

    • offset (number, optional): Page offset, default 0.

    • externalId (string, optional): External id of the payment.

• get-outgoing-payment

  • Get details of a specific outgoing payment.

  • Inputs:

    • paymentHash (string): The payment hash of the outgoing payment.

Node management

• get-node-info

  • Get the node info.

  • Inputs: none

• get-balance

  • Get the balance of the node.

  • Inputs: none

• list-channels

  • List the node channels.

  • Inputs: none

• close-channel

  • Close a channel by ID, sending the funds to a specified address on chain, with a specified fee rate.

  • Inputs:

    • channelId (string): The ID of the channel to close.

    • address (string): The Bitcoin on chain address to send the funds to.

    • feerateSatByte (number): The fee rate in satoshis per byte.

• decode-invoice

  • Decode a bolt11 invoice, the output amount is in millisatoshis.

  • Inputs:

    • invoice (string): The bolt11 invoice to decode.

• decode-offer

  • Decode a bolt12 offer, the output amount is in millisatoshis.

  • Inputs:

    • offer (string): The bolt12 offer to decode.

Troubleshooting

Authentication failed / 401 — Check that HTTP_PASSWORD matches the value in ~/.phoenix/phoenix.conf.

Connection refused — Phoenixd is not running or is listening on a different host/port. Verify with curl http://127.0.0.1:9740/getinfo -u :your_password.

Node.js version error — This package requires Node.js >= 18. Run node --version to check.