Alby MCP Server
Alby MCP Server is the bridge between an AI agent and a Lightning wallet: useful for paid workflows, dangerous if permissions are loose, and worth testing like a payment terminal rather than a novelty chat plugin.
What Alby MCP Server really is
Alby MCP Server is not a wallet, not a Nostr client and not an AI model. It is a bridge. On one side sits an MCP-capable client such as Claude Desktop, Claude Web, Goose, Cline, Windsurf, n8n or another agent framework. On the other side sits a Lightning wallet that supports Nostr Wallet Connect. The server exposes wallet actions as MCP tools so an agent can ask for invoices, parse invoices, pay invoices, check wallet information or fetch paid resources.
The current public repository is `getAlby/mcp`. Its description says it connects a Bitcoin Lightning wallet to an LLM using Nostr Wallet Connect and Model Context Protocol. The npm package is `@getalby/mcp`, version `1.1.1` when checked on June 13, 2026. The older `getAlby/nwc-mcp-server` repository is explicitly marked deprecated and points readers to the new repository. That distinction matters because old blog posts, examples and search results may still use the earlier name.
The right mental model is a payment terminal for agents. If you configure it well, an AI workflow can pay a small Lightning invoice, request an invoice from a Lightning Address, unlock an L402 resource or help account for payments. If you configure it loosely, the same agent path can become an overly broad spending permission. The product is exciting because it is real money. It is risky for the same reason.
Why this belongs in AI
Alby MCP Server belongs in the AI group because its user interface is usually not a normal web page. The visible surface is an agent chat, workflow builder or coding assistant. The payment capability appears inside that AI environment as tools the model can call. That makes it different from a wallet interface such as Alby Go, Zeus or BitBanana, and different from a developer library such as the Alby JS SDK by itself.
It also belongs in the Nostr ecosystem because the wallet bridge is Nostr Wallet Connect. NWC lets an app send wallet requests over Nostr relays to a wallet service that has granted permission. The MCP server does not invent a new payment network for AI. It wraps NWC and related Lightning utilities in the MCP format so agent clients can discover and call them.
This is a useful pattern for paid agents, autonomous workflows and small machine-to-machine payments. A research assistant could pay for an L402-protected article. A support bot could create invoices. A workflow could request payment before running an expensive n8n path. But each example should be designed with a narrow spending envelope. AI convenience should not turn a wallet connection into a blank check.
The current project replaced the old one
The name history is easy to mix up. The deprecated repository `getAlby/nwc-mcp-server` describes itself as a server for controlling a Lightning wallet using Nostr Wallet Connect, then tells readers to use `getAlby/mcp` instead. The current repository uses the title Alby Bitcoin Payments MCP Server and keeps the package name `@getalby/mcp`.
The current repository was created on June 2, 2025. GitHub API data checked on June 13, 2026 showed 67 stars, 17 forks, five open issues, TypeScript as the primary language, default branch `master`, repository update on June 7, 2026 and latest push on May 16, 2026. The latest GitHub release was `v1.1.1`, published July 16, 2025, and the npm registry also showed `1.1.1` as the latest version.
There is a small licensing detail builders should notice. The repository LICENSE file and GitHub license metadata show Apache-2.0, while the npm package metadata declares MIT. That may be accidental metadata drift, but it is worth checking before embedding the package in a commercial product. For ordinary users, the more urgent question is still permission scope, not license text.
How the connection is made
The server needs an NWC connection string. In local STDIO mode, the README asks you to run the package through `npx -y @getalby/mcp` and provide `NWC_CONNECTION_STRING` as an environment variable. In HTTP mode, the remote server accepts the NWC secret either as Bearer authorization or as an encoded `nwc` query parameter. The README says Bearer authorization is preferred.
The code confirms that behavior. `auth.ts` accepts a Bearer token only when it starts with `nostr+walletconnect://`, and it also accepts an `nwc` query parameter with the same prefix. `index.ts` uses the environment variable in STDIO mode and starts an Express server in HTTP mode. `streamable_http.ts` creates a new NWC client and a new MCP transport for each HTTP request. `sse.ts` supports the older SSE transport and stores per-session transports in memory.
That architecture gives users options, but it also creates a serious security choice. A Bearer header is cleaner than putting a wallet secret into a URL because URLs can be copied, logged, synced, shared or retained by tools. A local STDIO process can reduce remote exposure, but then your desktop configuration stores the secret. There is no version where the NWC string stops being a credential. It is the credential.
The hosted endpoint is convenient
Alby documents a hosted MCP server for clients that support remote MCP. The Streamable HTTP endpoint is `https://mcp.getalby.com/mcp`, and the SSE endpoint is `https://mcp.getalby.com/sse`. The README gives examples for Claude Web, Claude Desktop, Goose Desktop, Goose CLI, Cline, Claude Code, n8n and Windsurf. For users who only want to test a small payment flow, that hosted endpoint lowers the setup cost.
The convenience should not hide the trust shape. A remote MCP server receives the NWC connection secret you provide to it, then uses that secret to talk to your wallet service. The code creates an NWC client from the supplied secret for each remote request. That does not automatically mean Alby can spend anything beyond your NWC connection permissions, but it does mean the permission boundary must be set at the wallet connection, not in the chat UI.
If you use the hosted endpoint, create a dedicated app connection with a tiny budget, the minimum methods needed and a clear name such as `AI test MCP`. Do not reuse the same NWC connection that funds a serious business workflow. Do not paste a main wallet connection into a random agent experiment. The endpoint is a tool; your wallet limits are the guardrail.
Local STDIO is the tighter default
By default, the package runs in STDIO mode. That is the common MCP shape for desktop clients: the client starts a local command, talks to it through standard input and output, and the server reads the NWC connection string from an environment variable. The README includes a Claude Desktop configuration using `npx`, the package name and `NWC_CONNECTION_STRING`.
Local STDIO reduces the number of remote systems that see the connection string, but it does not remove secret handling. Your MCP client configuration, terminal history, environment management and local process logs become part of the security surface. On a shared computer, a copied JSON config can leak the wallet connection. On a managed machine, endpoint monitoring could capture environment values depending on policy.
The practical advantage is control. You can inspect the package version, pin it if needed, run the MCP inspector, read the source and keep the NWC secret local to the machine that needs it. For a builder or careful operator, local STDIO is usually the first serious test path. Remote HTTP is useful when the agent environment cannot run local commands or when a workflow platform expects a network endpoint.
The registered wallet tools are concrete
`mcp_server.ts` is the best source for understanding the server. It creates a `McpServer` named `@getalby/mcp`, version `1.1.1`, title `Alby MCP Server`, then registers two families of tools. The NWC family covers wallet service info, node info, invoice creation, invoice payment, balance, invoice lookup and transaction listing. The Lightning utility family covers L402 fetching, fiat conversion, invoice parsing and invoice requests from Lightning Addresses.
The NWC tools map closely to wallet actions. `get_balance` reads the connected wallet balance and returns sats after converting from millisats. `get_info` returns node and connection information such as alias, pubkey, network, methods, notifications, metadata and Lightning Address. `get_wallet_service_info` returns capabilities, encryption types and notification support. `make_invoice` creates an invoice. `pay_invoice` pays one. `lookup_invoice` reads payment state. `list_transactions` can filter by time, direction, limit, offset and unpaid status.
The utility tools widen the surface beyond direct wallet RPC. `parse_invoice` decodes a BOLT-11 invoice. `request_invoice` asks a Lightning Address for an invoice through LNURL. `fiat_to_sats` converts a fiat amount into sats using Alby Lightning Tools. `fetch_l402` uses a Nostr WebLN provider backed by the NWC client to fetch a paid L402 resource. These are useful tools, but they are not harmless read-only helpers when combined with payment permissions.
Paying invoices is the sharp edge
The most sensitive tool is `pay_invoice`. Its input schema accepts a BOLT-11 invoice, an optional amount in sats for zero-amount invoices, and optional metadata. The implementation converts sats to millisats for NWC and returns a payment preimage plus fees paid in sats when available. That means an agent can settle an invoice if the connected wallet allows the method and budget.
This is where human review matters. A model can misunderstand a prompt, parse a malicious page, be pushed by tool instructions from another source or simply pay the wrong invoice. NWC limits can keep the mistake small. Client-side approval prompts can help. A dedicated wallet with low balance can help. None of those controls should be skipped because the demo looked smooth.
For real use, set a spending budget that matches the task, not your curiosity. If the agent only needs to buy a five-sat test resource, do not give it a million-sat daily allowance. If it only needs to create invoices, do not grant pay permissions. If the wallet service supports method-level permissions, use them. The best AI payment setup is boring when something goes wrong.
Creating invoices is not risk free
`make_invoice` is less dangerous than paying an invoice, but it still deserves care. The tool accepts an amount, optional expiry, optional description, optional description hash and optional metadata. It calls the NWC client with the amount converted into millisats and returns transaction-like invoice details. An agent can therefore create payment requests on behalf of the connected wallet.
Invoice creation is useful for commerce workflows. A support agent could create a payment request for a service upgrade. A paid chat workflow could create an invoice before unlocking a response. A content workflow could request a small payment before generating an expensive output. In those cases, the MCP server makes Lightning feel like a normal tool call instead of a separate wallet ceremony.
The risk is operational confusion. If agents create invoices with poor descriptions, wrong amounts, long expiries or uncontrolled metadata, accounting becomes messy. If a workflow creates many invoices automatically, the wallet history can become noisy. If invoices are shown to customers, the wording matters. A payment agent should be tested for invoice content, not only payment success.
Read tools still reveal wallet context
The read-oriented tools are useful for planning and accounting, but they are not neutral. `get_balance` exposes wallet balance. `list_transactions` exposes transaction history with filters. `lookup_invoice` can reveal invoice state, payment hash, amount, timestamps, descriptions and fees. `get_info` can expose node metadata, pubkey and supported methods.
That matters because an AI client may store transcripts, tool outputs and logs. If a support workflow includes wallet history in a model context window, that data may be retained by the client or provider depending on settings. If an agent is connected to a public automation platform, tool output might be visible to more people than the wallet owner expects.
A careful setup separates read and spend permissions. A reporting agent may need balance and transaction listing but not payment. A payment agent may need pay permissions but not a broad historical export. A debugging session may need service info only. Do not treat all NWC methods as one switch if your wallet can offer narrower grants.
Lightning Address and LNURL are part of the bridge
The `request_invoice` tool shows that Alby MCP Server is not only a direct NWC wrapper. It can take a Lightning Address, an amount, optional description and optional payer data, then use Alby Lightning Tools to fetch LNURL data and request a BOLT-11 invoice. That makes the agent useful with recipients who publish Lightning Addresses rather than pre-generated invoices.
This is a practical workflow for chat and automation. A user can ask an agent to send 100 sats to a Lightning Address, the tool can request the invoice, and the payment tool can then pay it if permission exists. A workflow can also request invoices from known service addresses. The value is that Lightning Address becomes programmable inside the agent context.
The limit is verification. Lightning Address resolution depends on the recipient domain, the LNURL response and any metadata returned. A model should not improvise recipient addresses from vague text. A user should review the resolved recipient, amount and memo before payment. A domain typo is still a domain typo, even when an AI produced it politely.
L402 gives agents a paid resource path
`fetch_l402` is one of the most interesting tools because it points to a paid web rather than only wallet operations. L402 is a Lightning-based pattern for metered APIs and paid resources. The Alby MCP implementation uses `fetchWithL402` from Alby Lightning Tools and a Nostr WebLN provider backed by the NWC client. If the resource asks for payment, the connected wallet path can satisfy the challenge.
That is a natural fit for AI agents. An agent may need to fetch a premium data point, call a metered API, unlock a document or pay a small amount for a compute result. With MCP, that action becomes a tool call. With NWC, the wallet does not need to be embedded inside the agent. With L402, the resource can ask for payment at the HTTP boundary.
The risk is silent spending through retrieval. A user might think an agent is merely browsing, while the tool is actually authorized to pay for protected resources. The safe pattern is explicit user intent, tight budgets, clear logs and small tests. Paid fetches should be visible in the wallet history and in the agent's explanation to the user.
MCP transports change the threat model
Model Context Protocol supports different transports, and Alby MCP Server uses more than one. STDIO is the local command path. Streamable HTTP is the current remote path. SSE is still supported but called deprecated in the README and in the source comments. The choice affects where the server runs, where secrets live, how client sessions are handled and which logs might capture requests.
The Model Context Protocol documentation describes STDIO as a local transport and Streamable HTTP as a network transport for remote servers. Alby follows that shape. The hosted Alby endpoint is convenient for tools that can add custom connectors. Local STDIO is better when you want to keep the NWC connection on your own machine. HTTP mode can also be self-hosted if you deploy the server yourself.
For a wallet tool, transport is not only a developer preference. A query parameter secret can land in logs. A remote Bearer token can be handled by a third-party service. A local config can be synced to cloud storage. A self-hosted HTTP server can be exposed accidentally. Before you connect real funds, draw the data path from agent client to MCP server to NWC relay to wallet service.
Alby Hub is the natural wallet side
Alby MCP Server can work with wallets that support NWC, but Alby Hub is the natural pairing because it is Alby's own wallet service and app-connection surface. Alby Hub lets a user create app connections, set budgets and revoke permissions. That is exactly the control layer an AI payment agent needs. The MCP server should not be the first place where risk is limited; the wallet connection should be.
A good Alby Hub setup starts with a separate connection for the agent. Name it clearly. Limit the budget. Limit the methods if the wallet interface allows it. Prefer a short-lived test connection while building. Keep a small wallet balance until the workflow is boring. Revoke the connection after a demo, workshop or experiment. Those habits matter more than the beauty of the agent prompt.
If you use a different NWC wallet, apply the same logic. The connection string should be revocable. It should not have unlimited access unless the wallet holds only disposable funds. You should know which relays the wallet uses, whether the wallet service is local or hosted, and how quickly you can cut off the agent if a client behaves unexpectedly.
The old WebLN habit still appears
Alby MCP Server uses the modern NWC path, but it also leans on familiar WebLN ideas through the Alby SDK. In `mcp_server.ts`, the L402 tool receives a `NostrWebLNProvider` created from the NWC client. That is a useful abstraction because older web payment tooling often expects a WebLN-like provider while the actual wallet connection can run over Nostr Wallet Connect.
This is one reason the Alby ecosystem matters. The MCP server does not stand alone. It depends on `@getalby/sdk` for NWC client behavior and on `@getalby/lightning-tools` for Lightning Address, invoice, fiat and L402 helpers. The codebase is small because those libraries do much of the protocol work. Builders should evaluate the dependency stack, not only the MCP wrapper.
For users, the takeaway is simpler. If an agent can pay through Alby MCP, it is probably using a chain of abstractions: MCP tool call, Alby MCP server, NWC client, Nostr relays, wallet service, Lightning node or wallet backend. When something fails, the error may live in any one of those layers. Testing should include wallet connectivity, relay reachability, invoice creation, invoice settlement and tool output handling.
Agent clients need their own guardrails
The README lists many client examples, but each client handles tools differently. Claude Desktop and Claude Web have connector flows. Goose has desktop and CLI extension setup. Cline and Windsurf use configuration files. Claude Code can add a remote HTTP MCP server with a header. n8n can connect through native MCP client tools or community nodes. The same wallet permission can feel very different in each interface.
A serious test should check the client, not only the server. Does the client show tool names before calling them? Does it ask the user to approve a payment tool? Does it hide environment variables from chat transcripts? Does it log headers? Does it retry failed requests? Does it pass tool output back into the model in a way that exposes wallet history? These details decide whether the setup is acceptable.
For automation platforms such as n8n, the workflow design matters even more. A workflow can put a paid chat behind a Lightning invoice, chain MCP tools together and run unattended. That is powerful. It also means one miswired condition can create repeated invoices, repeated payment attempts or exposed connection strings. Build with a tiny test wallet until every branch is understood.
How to test it without getting burned
Start with a fresh NWC connection and a tiny balance. Use a wallet you can afford to drain during testing. Confirm the exact methods granted to the connection. If you only need to parse invoices or request Lightning Address invoices, avoid granting payment. If you need payment, use a very small budget and a short test window.
Then verify the transport. For local STDIO, check the MCP client configuration and make sure the secret is not committed to a repository, pasted into a prompt or synced into a shared folder. For hosted HTTP, prefer the Bearer header over the query parameter if the client supports it. For self-hosted HTTP, keep the endpoint behind access control and avoid public logs that capture authorization headers.
Finally, run a boring payment script by hand. Ask for wallet service info, ask for balance, parse a known invoice, request a Lightning Address invoice for a tiny amount, create a tiny invoice, then pay a tiny invoice only after reviewing it. Check the wallet history and the agent transcript. If the model cannot explain what happened, do not connect more money.
Where the limits are
Alby MCP Server does not make AI agents trustworthy. It gives them a controlled way to use a wallet connection. Trust still depends on the client, the model, the prompt, the MCP server, the NWC wallet, relay reliability, Lightning liquidity and the operator's permissions. A strong wallet budget can reduce loss, but it does not correct every wrong business action.
It also does not replace accounting. If an agent pays invoices or creates invoices, your business still needs records, memos, reconciliation, tax treatment and customer support. The `list_transactions` and `lookup_invoice` tools can help, but the agent output is not a ledger by itself. For larger flows, you need a real process around the wallet.
There is also a protocol-maturity limit. MCP is moving quickly, remote transports are still settling across clients, and wallet clients differ in how they implement NWC. An example that works in one client may fail in another. A wallet that supports one NWC method may not support another. Treat each agent-wallet pair as its own integration.
Who should use it now
Alby MCP Server is a good fit for developers, tinkerers, AI workflow builders, Lightning app teams and small teams testing paid agent workflows. It is especially useful if you already understand Alby Hub or another NWC wallet and want to put a narrow payment capability inside an MCP client. It is also useful for demonstrations of L402 and machine-to-machine Lightning payments.
It is not a good fit for a user who wants a set-and-forget AI wallet with a large balance. It is not a replacement for a point-of-sale terminal, an accounting system or a compliance process. It is not something to paste into an arbitrary agent with full wallet access. If the phrase `nostr+walletconnect://` feels like a random URL rather than a credential, pause and learn NWC first.
The best first use is small and reversible. Create a test connection. Run the MCP inspector or a desktop client. Pay a tiny invoice. Revoke the connection. Then decide whether the workflow deserves a more permanent budget. That slow path is not fear. It is how you keep AI payment tools useful instead of theatrical.
Closeout
Alby MCP Server is one of the clearest examples of why Nostr Wallet Connect matters outside normal wallet apps. It lets an agent act through a Lightning wallet without embedding the wallet inside the model or giving the agent a private key. That is a powerful architecture for a future where software can buy data, unlock services, receive invoices and settle tiny payments as part of ordinary workflows.
The tradeoff is that the pleasant chat interface can hide the payment credential underneath. The NWC string is not a harmless setup link. The MCP tool list is not a toy menu. The hosted endpoint is not a substitute for wallet limits. Use the project like you would use any payment integration: read the code, scope the connection, keep the first budget tiny, verify every method and revoke access when the job is done.
If you do that, Alby MCP Server is more than an AI demo. It is a practical bridge between Nostr Wallet Connect, Lightning and the emerging MCP tool layer. The bridge is worth using, but only when you can see both ends of it.
Sources worth opening
Start with the current `getAlby/mcp` repository and README, then inspect the package metadata and source files that register each tool. Compare that with NWC/NIP-47, Alby Hub app-connection docs, the MCP transport docs, Alby SDK, Alby Lightning Tools, LNURL and L402. The important question is not whether an AI can pay an invoice. It is which wallet methods the agent can call, how the NWC secret is delivered, where it is stored, what limits exist, and how quickly you can revoke it.
- Alby MCP repository
- Alby MCP README
- Alby MCP package.json
- Alby MCP mcp_server.ts
- Alby MCP index.ts
- Alby MCP auth.ts
- Alby MCP Streamable HTTP endpoint
- Alby MCP SSE endpoint
- Alby MCP get_balance tool
- Alby MCP get_info tool
- Alby MCP wallet service info tool
- Alby MCP make_invoice tool
- Alby MCP pay_invoice tool
- Alby MCP lookup_invoice tool
- Alby MCP list_transactions tool
- Alby MCP fetch_l402 tool
- Alby MCP fiat_to_sats tool
- Alby MCP parse_invoice tool
- Alby MCP request_invoice tool
- Alby MCP transaction schema
- Alby MCP invoice schema
- Alby MCP v1.1.1 release
- npm package @getalby/mcp
- Deprecated getAlby/nwc-mcp-server repository
- Alby AI page
- Awesome AI Bitcoin
- Alby CLI repository
- Alby PaidMCP repository
- Alby JS SDK repository
- Alby Lightning Tools repository
- Alby SDK NWC guide
- Alby Hub app connections
- Alby Hub getting started
- NWC official website
- NWC developer docs
- NWC best practices
- NIP-47 Nostr Wallet Connect
- Model Context Protocol documentation
- MCP transports documentation
- Official MCP TypeScript SDK
- Lightning Labs L402 documentation
- LNURL LUDs repository
- n8n SSE example
- n8n paid chat example
- Glama Alby MCP listing
