Btcpay Server MCP server

Connect Btcpay Server to Claude, ChatGPT, Cursor, Claude Code, Codex, Gemini, GitHub Copilot and any other MCP client, for your whole team. Metorial adds security, governance, and tracing, and gives everyone one Magic MCP URL to connect.

What you can do with the Btcpay Server MCP server

Ask your agent in plain language. Each of these maps to a real tool on the server.

  • Use the manage lightning tool in Btcpay Server
  • Use the get store payment methods tool in Btcpay Server
  • Use the manage payment requests tool in Btcpay Server
  • Use the manage payout claims tool in Btcpay Server
  • Use the get notifications tool in Btcpay Server
  • Use the refund invoice tool in Btcpay Server

Supported Tools

manage_lightning

Manage Lightning

Manage Lightning Network operations for a store, including checking balance, creating invoices, paying invoices (BOLT11), and viewing channels. Requires a connected Lightning node.

get_store_payment_methods

Get Store Payment Methods

Discover payment method IDs and enabled status for a store. Call manage_stores with action list to find a store. Requires btcpay.store.canviewstoresettings.

manage_payment_requests

Manage Payment Requests

Create, list, update, or archive shareable payment requests. Payment requests are pages where customers can pay on their own schedule with automatic exchange rate updates. Useful for freelancers, invoicing, or requesting money.

manage_payout_claims

Manage Payout Claims

List, retrieve, create, approve, cancel, or mark store payouts as paid. Call manage_stores to discover stores. Approval requires the actual current revision from list or get; cancellation and marking paid do not transfer funds. Create requires btcpay.store.cancreatenonapprovedpullpayments, plus btcpay.store.cancreatepullpayments when approved is true; list/get require btcpay.store.canviewpayouts; approve/cancel/mark_paid require btcpay.store.canmanagepayouts.

get_notifications

Get Notifications

Retrieve in-app notifications for the authenticated user. Covers events like invoice status changes, payouts, and version updates. Can filter by read/unread status and mark notifications as read.

refund_invoice

Refund Invoice

Issue a full or partial refund for a settled invoice. Returns a link where the customer can claim the refund. Supports different refund variants including original payment method, fiat, and custom amounts.

create_invoice

Create Invoice

Create a new payment invoice for a store. Invoices are the primary way to accept cryptocurrency payments. Supports configurable amounts, currencies, order IDs, buyer emails, custom metadata, and expiration.

manage_pull_payments

Manage Pull Payments

Create, list, or archive pull payments. Pull payments are long-lived payment offers from which recipients can pull (claim) funds at their convenience. The merchant specifies the total amount and can approve partial or full claims. Useful for recipient-initiated payments and refunds.

get_current_user

Get Current User

Get the authenticated BTCPay Server user profile without requesting server information. Requires btcpay.user.canviewprofile.

manage_payouts

Manage Payouts

DEPRECATED — use `manage_payout_claims` instead. List, approve, cancel, or mark payouts as paid. Payouts represent claims against pull payments that need to be processed. Supports both on-chain and Lightning payouts.

manage_wallet

Manage On-Chain Wallet

View on-chain wallet balance, list transactions, generate receive addresses, and create transactions for a store's wallet. Supports watch-only wallets and configured hot wallets.

get_server_info

Get Server Info

Retrieve information about the BTCPay Server instance, including version, supported payment methods, and current user details.

manage_invoice

Manage Invoice

Update invoice metadata, archive or unarchive an invoice, or manually mark its status. Discover stores with manage_stores and invoices with get_invoices. Manual marking requires btcpay.store.canmanageinvoicestatus; metadata and archive operations require btcpay.store.canmodifyinvoices.

get_invoices

Get Invoices

Retrieve a single invoice by ID or list invoices for a store with optional filtering by status, order ID, date range, and text search. Returns invoice details including status, amount, currency, and metadata.

manage_stores

Manage Stores

Create, list, retrieve, update, or delete stores on a BTCPay Server instance. Each store operates as an independent tenant with its own settings, payment methods, and wallets.

Connect Btcpay Server to your AI client

Every client uses the same Magic MCP URL, and so does any other MCP client. Add it once and sign in with SSO.

  1. Enable Btcpay Server in Metorial. In your Metorial portal, enable the Btcpay Server MCP server and sign in with the account that owns the data. Access stays governed by your team policies.
  2. Add a custom connector. Open Customize, then Connectors. Select Add, then Custom, then Web.
  3. Paste your Metorial MCP URL. Name it Metorial, paste your Magic MCP URL (<your-magic-mcp-url>) and continue.
  4. Sign in. Select Add and sign in to load Btcpay Server tools.

Run Btcpay Server through the Metorial gateway

One governed layer for every app your agents reach, not a separate connector per tool.

  • Give Btcpay Server and every other app to your whole team through one MCP gateway, behind your SSO.
  • Scope which teams and agents can use Btcpay Server tools with role-based access control, and trace every call.
  • Prefer to run it yourself? Metorial is open source and self-hostable.

More integrations teams use with Btcpay Server

Mailchimp

Manage email marketing audiences, campaigns, and automations. Create, send, schedule, and track email campaigns with detailed reporting on opens, clicks, and bounces. Add, update, and organize audience contacts with tags, segments, and interest groups. Set up and manage automation workflows triggered by subscriber activity or events. Connect e-commerce stores to manage customers, products, orders, and carts. Create and manage reusable email templates and landing pages. Upload and organize files for use in campaigns. Send transactional emails via the Mandrill API. Post custom events to trigger targeted automations. Configure webhooks to track subscribe, unsubscribe, profile updates, and email delivery events.

Zoho

Manage Zoho CRM, Bigin, Books, Inventory, Invoice, Desk, Mail, People, and Projects from one connection. Discover organizations and accounts, manage records and financial documents, work with support tickets and email, and organize employee and project data.

Quickbooks

Manage business finances and accounting in QuickBooks Online. Create, send, and track invoices. Manage bills and accounts payable, record bill payments. Create and update customer and vendor records with contact details and hierarchies. Record payments against invoices and credit memos. Create estimates, sales receipts, and journal entries. Track expenses and categorize against the chart of accounts. Manage items, products, services, and inventory levels. Query entities using SQL-like syntax and sync incremental changes via Change Data Capture. Generate financial reports including profit and loss, balance sheet, and cash flow. Process credit card and bank account (ACH) payments via the Payments API. Manage the chart of accounts for tracking income, expenses, assets, and liabilities.

Square

Process payments, manage orders, and handle invoices for online, in-app, and in-person commerce. Create and manage customer profiles, catalog items, inventory counts, and locations. Issue refunds, manage disputes, and track payouts. Create bookings and appointments, manage team members and timecards, handle gift cards and loyalty programs, and manage subscriptions. Save cards on file, generate checkout links, connect and control Square Terminal devices, and manage vendor/supplier information. Extend Square objects with custom attributes. Receive webhook notifications for payments, orders, customers, inventory, invoices, bookings, disputes, team changes, and more.

Gumroad

Manage digital and physical product sales on Gumroad. View and update product metadata, create and manage variant categories and options, and configure discount offer codes. Retrieve and filter sales data by date range for reporting. Manage subscribers and subscription lifecycles for recurring products. Refund sales, revoke or restore buyer access, and track payouts. Verify, enable, disable, and decrement license keys for purchase validation. Draft, schedule, and send audience emails to customers and followers. Read product reviews and access authenticated user profile information.

Stripe

Process payments, manage subscriptions, and handle invoices. Create and manage customers, payment methods, and product catalogs. Issue refunds, handle disputes, and submit chargeback evidence. Create checkout sessions and payment links. Manage connected accounts and platform fund flows via Stripe Connect. Configure payouts to bank accounts and debit cards. Apply coupons and promotion codes to subscriptions and invoices. Calculate and collect taxes automatically. Access balance information and transaction history. Upload files for dispute evidence and identity verification. Create and manage virtual and physical payment cards via Issuing. Receive real-time webhook notifications for payment, subscription, invoice, and account events.

Technical notes for Btcpay Server

Accept cryptocurrency payments with BTCPay Server. Manage stores, invoices, refunds, payment requests, pull payments, and payout claims. Inspect on-chain wallets and connected Lightning nodes, discover payment methods, and retrieve user profiles and notifications.

Frequently asked questions

Common questions about connecting Btcpay Server to AI agents with Metorial.

  1. How many tools does the Btcpay Server MCP server have?
    The Btcpay Server MCP server exposes 15 tools, including Manage Lightning, Get Store Payment Methods, Manage Payment Requests. Each one is governed and traced through Metorial.
  2. Btcpay Server exposes tools your agents call on demand; it does not publish event triggers yet. Everything still runs through one governed MCP URL.
  3. Any MCP client, including VS Code, Windsurf, Zed, OpenCode and Grok. Each one reaches the Btcpay Server MCP server through the same Metorial URL.
  4. Use role-based access control to decide which teams, users, and agents can use Btcpay Server and which of its tools they can call.
  5. Yes. Metorial is open source, so you can run the Btcpay Server MCP server yourself or use the hosted gateway.

Connect Btcpay Server to production AI agents

See how Metorial gives your team governed access to Btcpay Server, with tracing and security controls built in.