Log inSubmit server
BTCPay Server MCP logo

BTCPay Server MCP

Manage BTCPay Server invoices, stores, payments, Lightning data, wallets, webhooks, and exchange rates through MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install BTCPay Server MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "btcpay-server-mcp": {
      "command": "uvx",
      "args": [
        "btcpay-mcp"
      ],
      "env": {
        "BTCPAY_BASE_URL": "YOUR_VALUE_HERE",
        "BTCPAY_API_KEY": "YOUR_VALUE_HERE",
        "BTCPAY_STORE_ID": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

BTCPay Server MCP MCP server connects AI agents to BTCPay Server through its Greenfield REST API. It exposes 21 tools for invoices, stores, payment methods, pull payments, payment requests, payouts, refunds, webhooks, Lightning data, wallet activity, and exchange rates. The server uses a BTCPay API key and store configuration supplied through environment variables, then communicates over stdio. Reach for it when an agent needs to operate or inspect merchant payment processing rather than query general blockchain data.

Use cases

  • Create invoices for customer orders
  • Check invoice payment status
  • Create reusable payment requests
  • Monitor Lightning channels and wallet balances
  • Configure payment notification webhooks

Key features

  • Invoice creation and status lookup
  • Store and payment-method inspection
  • Pull payments and payment requests
  • Lightning and wallet monitoring
  • Webhook creation and listing
  • BTCPay exchange-rate lookup

Tools21

What BTCPay Server MCP lets your agent do. Expand a tool for its parameters.

Self-reported~352 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

6/6 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · btcpay-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

Last commit2mo agoMost recent push to the default branch.
Tools exposed21Callable tools this server registers over MCP.

How BTCPay Server MCP works

What the BTCPay Server MCP MCP server does

BTCPay Server MCP MCP server gives an MCP-compatible agent access to merchant operations in BTCPay Server. It uses the Greenfield REST API and provides 21 tools covering store inspection, invoice workflows, payment links, payouts, refunds, Lightning information, wallet activity, webhooks, and exchange rates.

The server can create invoices with an amount, currency, order ID, and description, then retrieve individual invoice status, received payments, metadata, and timing. Agents can also filter invoice listings by status. Store-oriented tools expose accessible stores, store configuration, and enabled on-chain or Lightning payment methods.

Payment operations include pull payments for donations, subscriptions, or payroll; payment requests for reusable payment pages; payout listings; and invoice refunds. A refund creates a pull payment. Webhook tools list existing hooks and create new ones for payment event notifications.

How it works

The BTCPay Server MCP MCP server runs as a Python MCP process and communicates with clients over stdio. Requests from the agent are translated into calls to BTCPay Server’s Greenfield API v1. Authentication uses a bearer token supplied through BTCPAY_API_KEY.

Additional tools expose operational data from configured payment infrastructure. Lightning tools return node information, including alias, version, peers, channels, and balance, while channel listings include capacity, balances, and status. Wallet tools report confirmed and unconfirmed on-chain balances and list wallet transactions. The exchange-rate tool retrieves the current BTC-to-fiat rate from BTCPay Server.

The server does not provide general blockchain data or node RPC access. Its scope is BTCPay merchant payment processing and related store infrastructure.

Setup and configuration

Install the package with pip install btcpay-mcp, or run it through uvx btcpay-mcp. Configure the MCP client with a command of uvx, the package name as its argument, and these environment variables:

  • BTCPAY_BASE_URL: URL of the BTCPay Server instance. The documented default is the BTCPay testnet demo URL.
  • BTCPAY_API_KEY: API key created in BTCPay Server under account or store API-key settings.
  • BTCPAY_STORE_ID: Default store ID used for invoice operations.

The API key must have appropriate permissions for the operations an agent will perform. The README provides configurations for Claude Desktop, Cursor, VS Code, and Claude Code. It also documents direct execution after setting the variables in the shell.

Tools and capabilities

The BTCPay Server MCP MCP server includes tools for:

  • Inspecting server version, synchronization status, supported methods, stores, store settings, and payment methods.
  • Creating, retrieving, and listing invoices, including optional status filtering.
  • Reading BTC/fiat exchange rates from BTCPay Server.
  • Creating and listing pull payments, payouts, payment requests, and webhooks.
  • Retrieving payment-request details and creating invoice refunds.
  • Inspecting Lightning node information and channel state.
  • Reading on-chain wallet balances and transaction history.

Use it for agent-assisted checkout administration, payment-status lookup, recurring or reusable payment flows, payment-event configuration, and operational monitoring of Lightning or wallet data.

Limitations and notes

The server requires access to a BTCPay Server instance and an API key. Its default URL points to a testnet demonstration instance, but production deployments should set BTCPAY_BASE_URL explicitly.

Capabilities depend on the permissions of the configured API key and the payment methods available in the selected store. Refunds are represented by newly created pull payments, and the server is not intended to replace a blockchain-data or Bitcoin node-RPC MCP server.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about BTCPay Server MCP

BTCPay Server MCP is an MCP server that connects AI agents to BTCPay Server through its Greenfield REST API. Its main tools manage stores, invoices, payment requests, pull payments, payouts, refunds, webhooks, Lightning data, wallet balances and transactions, and BTC/fiat exchange rates.

Install it with `pip install btcpay-mcp` or run it with `uvx btcpay-mcp`. Configure the MCP client to launch the command and provide `BTCPAY_BASE_URL`, `BTCPAY_API_KEY`, and `BTCPAY_STORE_ID` as environment variables.

Yes, BTCPay Server MCP works with Cursor over stdio. Add the server to `.cursor/mcp.json`, use `uvx` with `btcpay-mcp` as the argument, and set the BTCPay URL, API key, and store ID in the configuration.

It can create, retrieve, and list invoices, with optional status filtering. Invoice creation accepts an amount, currency, order ID, and description, while invoice details include payment status, received payments, metadata, and timing.

Yes, it exposes Lightning node information, channel listings, and balances, along with on-chain wallet balances and transaction history. Lightning results include details such as node alias, peers, channel capacity, balances, and status.

Related MCP servers

All in Finance & Fintech All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBTCPay Server MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/btcpay-server-mcp?style=directory)](https://allmcps.com/mcp/btcpay-server-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/btcpay-server-mcp"><img src="https://allmcps.com/api/badge/btcpay-server-mcp?style=directory" alt="BTCPay Server MCP on AllMCPs" /></a>