Alby Bitcoin Payments Extension

This tutorial covers how to add the Alby Bitcoin Payments MCP Server as a goose extension to interact with your lightning wallet, make and receive payments, list transactions, convert fiat amounts to sats, request invoices from lightning addresses, and interact with paid MCP tools (such as ones built with PaidMCP).

info

You'll need a lightning wallet that supports NWC. If you don't have one yet, consider trying Alby Hub.

TLDR

goose Desktop

Launch the installer

goose CLI

Command

npx -y @getalby/mcp

Environment Variable

NWC_CONNECTION_STRING: nostr+walletconnect://...

Configuration

info

You'll need Node.js installed on your system to run this command, as it uses npx

or you can use the Alby-hosted MCP (see remote options below).

goose Desktop

Local

1. Launch the installer
2. Click Yes to confirm the installation
3. Obtain a NWC Connection secret from your lightning wallet (nostr+walletconnect://...) and paste it in to the 'NWC Connection Secret' field
4. Click Add Extension
5. Click the button in the top-left to open the sidebar
6. Navigate to the chat

Remote

1. Launch the installer
2. Click Yes to confirm the installation
3. Obtain an NWC connection secret from your lightning wallet and paste it as the Bearer token (Bearer nostr+walletconnect://...)
4. Click Add Extension
5. Click the button in the top-left to open the sidebar
6. Navigate to the chat

goose CLI

Local

1. Run the configure command:

goose configure

2. Choose to add a Command-line Extension.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension 
│
◆  What type of extension would you like to add?
│  ○ Built-in Extension
│  ● Command-line Extension (Run a local command or script)
│  ○ Remote Extension (SSE)
│  ○ Remote Extension (Streaming HTTP)
└

3. Give your extension a name.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◆  What would you like to call this extension?
│  Alby
└

4. Enter the command to run when this extension is used.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension 
│
◇  What would you like to call this extension?
│  Alby
│
◆  What command should be run?
│  npx -y @getalby/mcp
└

5. Enter the number of seconds Goose should wait for actions to complete before timing out. Default is 300 seconds.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◇  What would you like to call this extension?
│  Alby
│
◇  What command should be run?
│  npx -y @getalby/mcp
│
◆  Please set the timeout for this tool (in secs):
│  300
└

6. Enter a description for this extension.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◇  What would you like to call this extension?
│  Alby
│
◇  What command should be run?
│  npx -y @getalby/mcp
│
◇  Please set the timeout for this tool (in secs):
│  300
│
◆  Enter a description for this extension:
│  Connect goose to your Bitcoin Lightning Wallet
└

7. Add an environment variable for this extension.

info

Obtain an NWC Connection secret from your lightning wallet (nostr+walletconnect://...) and paste it in.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Command-line Extension
│
◇  What would you like to call this extension?
│  Alby
│
◇  What command should be run?
│  npx -y @getalby/mcp
│
◇  Please set the timeout for this tool (in secs):
│  300
│
◇  Enter a description for this extension:
│  Connect goose to your Bitcoin Lightning Wallet
│
◆  Would you like to add environment variables?
│  Yes
│
◇  Environment variable name:
│  NWC_CONNECTION_STRING
│
◇  Environment variable value:
│  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
│
◇  Add another environment variable?
│  No
│
└  Added Alby extension

Remote

1. Run the configure command:

goose configure

2. Choose to add a Remote Extension (Streaming HTTP).

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension 
│
◆  What type of extension would you like to add?
│  ○ Built-in Extension
│  ○ Command-line Extension
│  ○ Remote Extension (SSE)
│  ● Remote Extension (Streaming HTTP) (Connect to a remote extension via MCP Streaming HTTP)
└

3. Give your extension a name.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Remote Extension (Streaming HTTP)
│
◆  What would you like to call this extension?
│  Alby
└

4. Enter the Streaming HTTP endpoint URI.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension 
│
◇  What type of extension would you like to add?
│  Remote Extension (Streaming HTTP)
│
◇  What would you like to call this extension?
│  Alby
│
◆  What is the Streaming HTTP endpoint URI?
│  https://mcp.getalby.com/mcp
└

5. Enter the number of seconds Goose should wait for actions to complete before timing out. Default is 300 seconds.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Remote Extension (Streaming HTTP)
│
◇  What would you like to call this extension?
│  Alby
│
◇  What is the Streaming HTTP endpoint URI?
│  https://mcp.getalby.com/mcp
│
◆  Please set the timeout for this tool (in secs):
│  300
└

6. Enter a description for this extension.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Remote Extension (Streaming HTTP)
│
◇  What would you like to call this extension?
│  Alby
│
◇  What is the Streaming HTTP endpoint URI?
│  https://mcp.getalby.com/mcp
│
◇  Please set the timeout for this tool (in secs):
│  300
│
◆  Enter a description for this extension:
│  Connect goose to your Bitcoin Lightning Wallet
└

7. Add a custom header for this extension.

info

Obtain an NWC connection secret from your lightning wallet and paste it as the Bearer token.

┌   goose-configure 
│
◇  What would you like to configure?
│  Add Extension
│
◇  What type of extension would you like to add?
│  Remote Extension (Streaming HTTP)
│
◇  What would you like to call this extension?
│  Alby
│
◇  What is the Streaming HTTP endpoint URI?
│  https://mcp.getalby.com/mcp
│
◇  Please set the timeout for this tool (in secs):
│  300
│
◇  Enter a description for this extension:
│  Connect goose to your Bitcoin Lightning Wallet
│
◆  Would you like to add custom headers?
│  Yes
│
◇  Header name:
│  Authorization
│
◇  Header value:
│  Bearer nostr+walletconnect://...
│
◇  Add another header?
│  No
│
└  Added Alby extension

Example Usage

LLM

Claude Sonnet 3.7 was used for this task. A similarly capable model is recommended to ensure the tool is used correctly.

Memory Extension

Use the built-in memory extension to save your contacts. e.g. "My friend Rene's lightning address is reneaaron@getalby.com. Please save it to your memory."

goose Prompt

Pay Rene $1 USD, with message "Hi Rene, it's Roland. I'm making a goose tutorial!"

goose Output

CLI

Tool Calls

─── fiat_to_sats | alby ──────────────────────────

fiat_amount: 1

fiat_currency: USD

─── request_invoice | alby ──────────────────────────

amount_in_sats: 935

description: ...

lightning_address: reneaaron@getalby.com

─── pay_invoice | alby ──────────────────────────

invoice: ...

✅ Payment Successful!

I've successfully sent $1 USD (935 sats) to Rene at reneaaron@getalby.com with your message: "Hi Rene, it's Roland. I'm making a goose tutorial!"

Transaction Details:

• Amount: 935 sats ($1 USD)
• Fees: 3 sats
• Total cost: 938 sats
• Message: "Hi Rene, it's Roland. I'm making a goose tutorial!"
• Payment hash: cd30642470d81c2e8eb04c9ac95e679c53778537aecdf5554b15288ac42fe129

Rene will receive the message "Thanks, sats received!" as confirmation of the payment.