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.

phoenixd-mcp-server

Quick Install