PaidMCP - Charge Bitcoin For MCP Server Tools

Receive lightning payments for each tool request, powered by NWC.

In a few lines of code, turn your modelcontextprotocol/sdk MCP Server tool into a paid tool:

- const server = new McpServer({name: "your-mcp-server"});
+ const server = new PaidMcpServer({name: "your mcp server"}, {nwcUrl});
- server.registerTool(name, config, callback);
+ server.registerPaidTool(name, config, charge, callback);

Get started

Install

npm install @getalby/paidmcp

or

yarn add @getalby/paidmcp

Import and use PaidMcpServer

PaidMcpServer is a thin wrapper around the standard McpServer class that adds ability to create paid tools.

This MCP requires an NWC-enabled lightning wallet to be able to charge payments. NWC is an open protocol for connecting apps to lightning wallets. If you don't have a NWC-enabled lightning wallet yet, try Alby Hub.

import { PaidMcpServer } from "@getalby/paidmcp";

// Configure your NWC URL - should be "nostr+walletconnect://..."
const nwcUrl = process.env.NWC_URL;
// use PaidMcpServer instead of McpServer
const server = new PaidMcpServer({ name: "your-mcp-server" }, { nwcUrl });

// for paid tools, use registerPaidTool
// it requires an additional argument before the callback
// to configure charging information based on the request
server.registerPaidTool(
  name,
  config,
  (args) => ({ satoshi: 1, description: "Paid tool usage: " + args.city }),
  callback
);

Examples

See weather example

How it works

For a simple example we have a paid weather MCP - that you can fetch the weather for a city by paying a small fee.

{
  "city": "Berlin"
}

Some additional parameters are injected into the tool request and response. If a paid tool is requested without a payment hash, the following response will be returned:

the required payment amount and description can be configured per-request.

{
  "payment_instructions": "Payment required. Pay the payment_request and try the same request again with the payment_hash set to continue.",
  "payment_request": "lnbc...",
  "payment_hash": "2b3e38cff2ab0172d28e004931938c09a19b3e81a2054c3b46ac087ec3bc30b3"
}

Once the payment is made by the human or their agent (this can be done with Alby MCP), the agent will request the same tool again, this time providing the payment_hash along with the request:

{
  "city": "Berlin",
  "payment_hash": "2b3e38cff2ab0172d28e004931938c09a19b3e81a2054c3b46ac087ec3bc30b3"
}

The MCP server will then execute the actual tool callback as normal.

{
  "temperature_celcius": "27.4"
}