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 ); } }