Bitcoin MCP Server

Instructions

Implementation Reference

• src/server/tools.ts:242-270 (handler)

  MCP tool handler for 'pay_invoice'. Validates input schema, calls bitcoinService.payInvoice(bolt11), and returns success response with payment hash or throws MCP error.

  export async function handlePayInvoice(
    bitcoinService: BitcoinService,
    args: unknown
  ) {
    const result = PayInvoiceSchema.safeParse(args);
    if (!result.success) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Invalid parameters: ${result.error.message}`
      );
    }
  
    try {
      const paymentHash = await bitcoinService.payInvoice(result.data.invoice);
      return {
        content: [
          {
            type: "text",
            text: `Payment successful!\nPayment hash: ${paymentHash}`,
          },
        ] as TextContent[],
      };
    } catch (error: any) {
      throw new McpError(
        ErrorCode.InternalError,
        error.message || "Failed to pay invoice"
      );
    }
  }

• src/types.ts:130-134 (schema)

  Zod schema defining input for pay_invoice tool: requires 'invoice' string.

  export const PayInvoiceSchema = z.object({
    invoice: z.string().min(1, "Invoice cannot be empty"),
  });
  
  export type PayInvoiceArgs = z.infer<typeof PayInvoiceSchema>;

• src/server/base.ts:177-189 (registration)

  Tool registration in listToolsRequestHandler: defines name, description, and inputSchema for 'pay_invoice'.

    name: "pay_invoice",
    description: "Pay a Lightning invoice",
    inputSchema: {
      type: "object",
      properties: {
        invoice: {
          type: "string",
          description: "BOLT11 Lightning invoice",
        },
      },
      required: ["invoice"],
    },
  } as Tool,

• src/server/base.ts:218-220 (registration)

  Dispatch/handling registration in callToolRequestHandler switch statement: routes 'pay_invoice' calls to handlePayInvoice.

  case "pay_invoice": {
    return handlePayInvoice(this.bitcoinService, args);
  }

• src/services/bitcoin.ts:306-324 (helper)

  Core helper method in BitcoinService that performs the actual invoice payment via LNBits client and returns payment_hash.

  async payInvoice(bolt11: string): Promise<string> {
    if (!this.lnbitsClient) {
      throw new LightningError(
        "LNBits not configured. Please add lnbitsUrl, lnbitsAdminKey, and lnbitsReadKey to configuration.",
        LightningErrorCode.NOT_CONNECTED
      );
    }
  
    try {
      const response = await this.lnbitsClient.sendPayment(bolt11);
      return response.payment_hash;
    } catch (error) {
      logger.error({ error, bolt11 }, "Failed to pay invoice");
      throw new LightningError(
        "Failed to pay Lightning invoice",
        LightningErrorCode.PAYMENT_ERROR
      );
    }
  }