Alby Bitcoin Payments MCP server
Commit Oct 21, 2026Connects a bitcoin lightning wallet to an AI client via Nostr Wallet Connect so it can make lightning payments and fetch L402 resources.
Also known as getAlby/mcp
- Stars
- 66
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 21, 2026
- License
- Apache-2.0
What is Alby Bitcoin Payments MCP?
Alby Bitcoin Payments connects a bitcoin lightning wallet to an AI client via Nostr Wallet Connect so it can make lightning payments and fetch L402 resources.
Summary generated from the project's README
About Alby Bitcoin Payments MCP server
Sending bitcoin lightning payments and paying for L402-gated resources straight from an AI client is what this server lets a developer do. It links a lightning wallet to an LLM through a Nostr Wallet Connect connection secret, and it carries knowledge of NWC, LNURL and L402 by way of the Alby SDK and Alby Lightning Tools. It is aimed at developers building agents that need to move small amounts of bitcoin or fetch content behind lightning paywalls.
You can run it locally or use Alby's hosted option. Locally it defaults to STDIO, launched with npx -y @getalby/mcp and an NWC_CONNECTION_STRING environment variable, and works with clients such as Claude Desktop, Cline and Goose CLI. The hosted version exposes SSE and HTTP Streamable transports and accepts the NWC secret as Bearer authentication or as a query parameter, and there is a Claude Code command for adding it. Setting MODE=HTTP serves the server on port 3000.
HTTP endpoints only accept allowlisted Host headers and refuse browser requests. The fetch_l402 tool only retrieves http(s) URLs resolving to globally routable addresses and does not follow redirects. Node.js 20+ and Yarn are needed to build from source, and a wallet that supports NWC is required.
What you can do with it
- 1Pay a lightning invoiceHave the agent settle a lightning invoice from the connected wallet while working through a task.
- 2Fetch an L402 paywalled resourceAsk the client to retrieve a URL protected by L402 so it pays the invoice and gets the content.
- 3Add wallet to Claude CodeRegister the hosted server with a bearer auth header so Claude Code can make lightning payments.
- 4Test tools without an LLMRun the inspector to exercise the server's tools directly before wiring them into an agent.
- 5Deploy self-hosted HTTP serverRun the server in HTTP mode behind a public hostname for a remote MCP client.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGENWC_CONNECTION_STRING
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegetalby/mcp is public and reachablegithub.com/getalby/mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-21github.com/getalby/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAlby Bitcoin Payments MCP Server
NEW: also checkout Alby CLI for agents that don't support MCP.
Connect a bitcoin lightning wallet to your LLM using Nostr Wallet Connect (NWC).
This MCP server uses the official MCP TypeScript SDK
This MCP server has knowledge of NWC, LNURL and L402 using Alby SDK and Alby Lightning Tools.
Take a look at Awesome AI Bitcoin for places where you can use the Alby MCP.
Quick Start
In case you get stuck, see troubleshooting section below.
Use the Alby-Hosted MCP Server
If your agent supports remote MCP servers - SSE (e.g. N8N) or HTTP Streamable transports, you can connect to Alby's MCP server.
- SSE:
https://mcp.getalby.com/sse - HTTP Streamable:
https://mcp.getalby.com/mcp
Authentication
Both require providing an NWC connection secret as authentication, either as Bearer authentication (preferred) or via the nwc query parameter.
Bearer Auth
Example: Authorization: Bearer nostr+walletconnect://...
If your agent UI supports bearer auth, just paste the connection secret into the bearer auth field.
Query Parameter
If your agent doesn't support bearer auth, you can pass the NWC connection secret as a query parameter.
Example: https://mcp.getalby.com/sse?nwc=ENCODED_CONNECTION_SECRET or https://mcp.getalby.com/mcp?nwc=ENCODED_CONNECTION_SECRET
To get ENCODED_CONNECTION_SECRET, open browser devtools (right click -> inspect) and enter this in the console, with your own NWC connection secret set:
encodeURIComponent("nostr+walletconnect://...");
In case there is a message asking for confirmation for pasting, follow the instructions, and then enter the above command again.
Once the command has run, copy the output and replace ENCODED_CONNECTION_SECRET. It will look like this: nostr%2Bwalletconnect%3A%2F%2F...
Add to Claude Web or Claude Desktop
Use the remote Alby MCP server
Currently, at least a Claude Pro subscription is required to be able to connect to remote MCP servers.
- Go to Settings -> Connectors
- Click on "Add custom connector"
- Call it
alby - What is the endpoint URI:
https://mcp.getalby.com/mcp?nwc=ENCODED_NWC_URL(see above for instructions)
Client-side
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"nwc": {
"command": "npx",
"args": ["-y", "@getalby/mcp"],
"env": {
"NWC_CONNECTION_STRING": "YOUR NWC CONNECTION STRING HERE"
}
}
}
}
Add to Goose Desktop
- Open Goose Desktop
- Go To Settings -> Advanced Settings
- Click on "Add custom Extension"
- Call it
alby, and change the type toHTTP Streamable - What is the SSE endpoint URI:
https://mcp.getalby.com/mcp - Timeout: 30
- Description: no
- environment variables: no
Add to Goose CLI
Use the Alby MCP server
- Type
goose configure - Add extension -> Remote Extension (HTTP Streamable)
- Call it
alby - What is the HTTP Streamable endpoint URI:
https://mcp.getalby.com/mcp - Timeout: 30
- Description: no
- environment variables: no
- add custom headers: yes
- header name:
Authorization - header value:
Bearer nostr+walletconnect://...(replace with your connection secret)
Client-side
- Type
goose configure - Add extension -> Command Line Extension
- Call it
alby - What command should be run:
npx -y @getalby/mcp - Timeout: 30
- Description: no
- environment variables: yes
- environment variable name:
NWC_CONNECTION_STRING - environment variable value:
nostr+walletconnect://...(your NWC connection secret here)
Add to Cline
Copy the below and paste it into a cline prompt. It should prompt you to update the connection string.
Add the following to my MCP servers list:
"nwc": {
"command": "npx",
"args": ["-y", "@getalby/mcp"],
"env": {
"NWC_CONNECTION_STRING": "nostr+walletconnect://..."
},
"disabled": false,
"autoApprove": []
}
Add to Claude Code
Use the Alby MCP server
claude mcp add --transport http alby https://mcp.getalby.com/mcp --header "Authorization: Bearer nostr+walletconnect://..."
Add to N8N via SSE
You can use the native N8N MCP Client tool connected to an AI agent. Enter your SSE endpoint, set authentication to "Bearer" and paste your NWC connection secret.
Tested with OpenRouter + anthropic/claude-3.7-sonnet
See the N8N workflow for a simple example
Add to N8N via STDIO (Community Node)
Currently this MCP server only works via command line (STDIO).
You can install the n8n-nodes-mcp community node and run n8n with tools enabled e.g.
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true npx n8n
Create a blank workflow and add an AI agent node. Configure your LLM model and add a new tool "MCP Client" (which will have a cube next to it showing it's a community node).
Configure the MCP Client by adding a credential with Command Line (STDIO) selected.
command: npx
arguments: -y @getalby/mcp
environments NWC_CONNECTION_STRING=nostr+walletconnect://your_key_here (create the whole line in a text editor and paste it in, since the password field cannot be switched to plaintext)
See the N8N paid chat workflow for a full example
Add to Windsurf
Use the remote Alby MCP server
- Download and open your Windsurf Editor
- Click on "Windsurf - Settings" in the toolbar at the bottom -> "Advanced Settings" -> "Cascade" -> Plugins (MCP Servers): Click on "Manage plugins" -> "View raw config" -> you'll see your "mcp_config.json"
- Paste this to your mcp_config.json:
{
"mcpServers": {
"alby": {
"serverUrl": "https://mcp.getalby.com/sse?nwc=ENCODED_NWC_URL"
}
}
}
- Replace "ENCODED_NWC_URL" as descripted above. Click "Save" and restart the Windsurf editor.
Modes
STDIO
By default NWC MCP Server runs locally in STDIO mode.
HTTP
You can set the following environment variable: MODE=HTTP which will enable Streamable HTTP (http://localhost:3000/mcp) and SSE (http://localhost:3000/sse Note: SSE is deprecated).
HTTP requires bearer authorization, where the token is a wallet's NWC connection secret. See the authentication section further above in the README.
Request validation
The HTTP endpoints only accept requests whose Host header is allowlisted. Requests from browsers (carrying an Origin header) are refused; MCP clients that aren't browsers don't send one. fetch_l402 only fetches http(s) URLs whose hostname resolves to globally-routable addresses — loopback, link-local and private ranges are refused. This is a best-effort check: the hostname is resolved again when fetching, so a DNS server that changes its answer between the two lookups can bypass it. Configure via environment variables:
| Variable | Default | Purpose |
|---|---|---|
ALLOWED_HOSTS |
localhost, 127.0.0.1, [::1] |
Host header values to accept (comma-separated). When set, it replaces the defaults, so include localhost if you still want it. Set this to your public hostname when deploying (e.g. mcp.getalby.com). |
BIND_HOST |
127.0.0.1 |
Address the HTTP listener binds to. The default keeps it off the network; set :: (or 0.0.0.0) when deploying, or when running in Docker and connecting from the host. |
fetch_l402 does not follow redirects; a URL that redirects returns an error.
From Source
Prerequisites
- Node.js 20+
- Yarn
- A connection string from a lightning wallet that supports NWC
Installation
yarn install
Building
yarn build
Add your NWC connection
Copy .env.example to .env and update your connection string
Inspect the tools (use/test without an LLM)
yarn inspect
Supported Tools
See the tools directory
Troubleshooting
Model Usage
Make sure you use a decent model (e.g. Claude Sonnet 3.7) otherwise the MCP server will not work.
Failure to connect to wallet, secret missing
Make sure you copied the entire NWC connection secret, without spaces
Contact Alby Support
Visit support.getalby.com and we're happy to help you get the MCP server working.
Alby Bitcoin Payments MCP questions
How do I authenticate with the remote Alby MCP server?
Pass your NWC connection secret as Bearer authentication, or as the nwc query parameter if your client does not support bearer auth.
What transport modes does the Alby MCP server support when run locally?
It runs in STDIO mode by default; setting MODE=HTTP enables Streamable HTTP and SSE on localhost port 3000.
Which bitcoin lightning standards does the server know about?
It has knowledge of NWC, LNURL, and L402, using the Alby SDK and Alby Lightning Tools.