mcp

This MCP server implements Alby’s Bitcoin payments integration via the Nostr Wallet Connect (NWC) protocol. It exposes a remote MCP interface that enables your AI agents or tools to interact with a connected lightning wallet (via NWC) for operations such as generating invoices, paying requests, or querying wallet state. The server is built on the official MCP TypeScript SDK and includes bindings to NWC, LNURL, and L402 capabilities through the Alby SDK ecosystem. You can connect to the MCP server over SSE or HTTP Streamable transports, and authenticate using an NWC connection secret either as a Bearer token or via a query parameter. The included examples show how to wire this MCP server into Claude, Goose, Claude Code, N8N, Windsurf, and other environments, making it straightforward to extend LLM-driven workflows with live Bitcoin payments.

To use, supply your NWC connection secret (the wallet connection string) to the MCP client. In environments that support bearer tokens, you can set the Authorization header to Bearer nostr+walletconnect://...; otherwise, pass the secret as a nwc query parameter. The server is designed to work with clients that support MCP transports (SSE or HTTP Streamable) and is compatible with tools that rely on the Alby SDK for wallet interactions.

Prerequisites:

• Node.js 20+ (recommended)
• Yarn (or npm, if preferred)
• A Nostr Wallet Connect (NWC) connection secret for your lightning wallet

Installation steps:

1. Install dependencies yarn install

2. Build the project (if applicable in this repo) yarn build

3. Configure your NWC connection

   • Copy .env.example to .env
   • Update NWC_CONNECTION_STRING with your wallet connection secret

4. Run the MCP server

   • If using the default Node/CLI setup demonstrated in the README, start the server via your preferred method (e.g., npx @getalby/mcp or via your runtime script according to your environment)

5. Verify tools and capabilities

   • Inspect the available tools under the tools directory to test interactions without an LLM: yarn inspect

Prerequisites recap: Node.js 20+, Yarn, and a valid NWC connection secret are required before starting the server.

Environment variables and configuration tips:

• NWC_CONNECTION_STRING is required when using the default 'nwc' MCP server configuration. Replace the placeholder with your actual wallet connection secret.
• If you need to expose the server via HTTP, you can set MODE=HTTP to enable HTTP endpoints (note that this enables Bearer authentication by default).
• For remote usage in Claude, Goose, or Claude Code, you can configure the client to point to the MCP endpoint and pass the NWC secret either as a bearer token or query parameter, as described in the README.
• When using Windsurf or other clients that expect a Windsurf-style config, you can add an entry like {"mcpServers": {"alby": {"serverUrl": "https://mcp.getalby.com/sse?nwc=ENCODED_NWC_URL"}}} and replace ENCODED_NWC_URL with your encoded secret.
• If you encounter wallet connection issues, ensure you pasted the entire NWC connection secret (no spaces) and that your environment has network access to the MCP server and wallet providers.