How do I install Btcpay?

Btcpay is a local plugin. Install it using the provided package and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

What AI apps work with Btcpay?

Btcpay uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Btcpay MCP Server

by ThomsenDrake

Developer ToolsLow Risk10.0MCP RegistryLocal

Free

Server data from the Official MCP Registry

21 tools for AI agents to manage BTCPay Server: invoices, payments, stores, webhooks, Lightning

About

21 tools for AI agents to manage BTCPay Server: invoices, payments, stores, webhooks, Lightning

Security Report

10.0

Low Risk10.0Low Risk

Valid MCP server (1 strong, 4 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry.

3 files analyzed · No issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

Documentation

View on GitHub

From the project's GitHub README.

btcpay-mcp

MCP server for BTCPay Server — let AI agents create invoices, manage stores, track payments, and check exchange rates through the Greenfield REST API.

21 tools · MIT licensed · Zero hardcoded credentials

The only MCP server for BTCPay Server. While other Bitcoin MCP servers cover blockchain data and node RPC, btcpay-mcp is the first to expose full merchant payment processing — invoice creation, store management, pull payments, payment requests, Lightning operations, wallet management, webhooks, and exchange rates — to AI agents.

pip install btcpay-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "btcpay-server": {
      "command": "uvx",
      "args": ["btcpay-mcp"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-server.com",
        "BTCPAY_API_KEY": "your-api-key",
        "BTCPAY_STORE_ID": "your-store-id"
      }
    }
  }
}

Claude Code

claude mcp add btcpay-server -- uvx btcpay-mcp

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "btcpay-server": {
      "command": "uvx",
      "args": ["btcpay-mcp"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-server.com",
        "BTCPAY_API_KEY": "your-api-key",
        "BTCPAY_STORE_ID": "your-store-id"
      }
    }
  }
}

Manual / pip install

pip install btcpay-mcp

# Set environment variables
export BTCPAY_BASE_URL="https://your-btcpay-server.com"
export BTCPAY_API_KEY="your-api-key"
export BTCPAY_STORE_ID="your-store-id"

# Run
btcpay-mcp

Or with pip install from source:

git clone https://github.com/toplyrnarfur/btcpay-mcp.git
# or: git clone https://codeberg.org/toplyr-narfur/btcpay-mcp.git
cd btcpay-mcp
pip install -e ".[dev]"
python -m btcpay_mcp.server

Tools

Tool	Description
`get_server_info`	BTCPay Server version, sync status, supported methods
`list_stores`	List all stores accessible with the API key
`get_store_info`	Store configuration: currency, speed policy, checkout type
`get_store_payment_methods`	Enabled payment methods: on-chain, Lightning, etc.
`create_invoice`	Create a new invoice (amount, currency, order ID, description)
`get_invoice`	Invoice status, payments received, metadata, timing
`list_invoices`	List invoices with optional status filter
`get_exchange_rate`	Current BTC/fiat exchange rate from BTCPay
`list_pull_payments`	List pull payments (donations, subscriptions, payroll)
`create_pull_payment`	Create pull payment for donations, subscriptions, or payroll
`list_payouts`	List actual payout transactions (claims against pull payments)
`list_payment_requests`	List payment requests (reusable payment links)
`create_payment_request`	Create a payment request (persistent payment page)
`get_payment_request`	Get payment request details and status
`list_webhooks`	List configured webhooks for payment event notifications
`create_webhook`	Create a webhook for real-time payment notifications
`refund_invoice`	Refund an invoice (creates pull payment)
`get_lightning_info`	Lightning node info: alias, version, peers, channels, balance
`list_lightning_channels`	List Lightning channels with capacity, balances, status
`get_wallet_balance`	On-chain wallet balance (confirmed/unconfirmed)
`list_wallet_transactions`	List on-chain wallet transactions

Top Use Cases

Ask your AI agent:

Prompt	What it does
"Create a $50 invoice for Order #1234"	Generates a BTC/Lightning invoice via BTCPay
"Show me all unpaid invoices"	Lists pending invoices across stores
"What payment methods does my store accept?"	Checks configured payment methods
"What's the BTC/USD rate right now?"	Fetches current exchange rate
"Show me the status of invoice inv_xxxx"	Retrieves full invoice details and payment status
"Set up a $100/month donation pull payment"	Creates a pull payment for recurring donations
"Create a payment request for my consulting service"	Creates a reusable payment link
"Show me my Lightning node info and balance"	Fetches LN alias, channels, and balances
"Check my on-chain wallet balance"	Gets confirmed/unconfirmed BTC wallet balance
"Set up a webhook for invoice settlements"	Creates a webhook for real-time payment notifications
"Refund invoice inv_xxxx"	Initiates a refund with configurable calculation method

Configuration

Variable	Default	Description
`BTCPAY_BASE_URL`	`https://testnet.demo.btcpayserver.org`	Your BTCPay Server URL
`BTCPAY_API_KEY`	(empty)	API key from BTCPay Server
`BTCPAY_STORE_ID`	(empty)	Default store ID for invoice operations

Creating a BTCPay API Key

Navigate to your BTCPay Server instance
Go to Account → API Keys or Store Settings → API Keys
Create a new API key with appropriate permissions
Note the API key and your store ID

API Endpoints

All from the BTCPay Server Greenfield API v1:

GET /api/v1/server/info — server version and info
GET /api/v1/stores — list stores
GET /api/v1/stores/{storeId} — store configuration
GET /api/v1/stores/{storeId}/payment-methods — enabled payment methods
POST /api/v1/stores/{storeId}/invoices — create invoice
GET /api/v1/stores/{storeId}/invoices — list invoices
GET /api/v1/stores/{storeId}/invoices/{invoiceId} — invoice details
GET /api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods — payment addresses
POST /api/v1/stores/{storeId}/invoices/{invoiceId}/refund — refund invoice
GET /api/v1/stores/{storeId}/pull-payments — list pull payments
POST /api/v1/stores/{storeId}/pull-payments — create pull payment
GET /api/v1/stores/{storeId}/payouts — list payouts
GET /api/v1/stores/{storeId}/payment-requests — list payment requests
POST /api/v1/stores/{storeId}/payment-requests — create payment request
GET /api/v1/stores/{storeId}/payment-requests/{id} — payment request details
GET /api/v1/stores/{storeId}/webhooks — list webhooks
POST /api/v1/stores/{storeId}/webhooks — create webhook
GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info — LN node info
GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance — LN balance
GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels — LN channels
GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet — wallet balance
GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet/transactions — wallet transactions
GET /api/v1/rates — exchange rates

How This Differs from Other Bitcoin MCP Servers

Feature	btcpay-mcp	bitcoin-mcp (Bortlesboat)
Invoice creation	✅ Yes	❌ No
Store management	✅ Yes	❌ No
Payment lifecycle	✅ Yes	❌ No
Pull payments	✅ Yes	❌ No
Payment requests	✅ Yes	❌ No
Webhooks	✅ Yes	❌ No
Refunds	✅ Yes	❌ No
Lightning node info	✅ Yes	❌ No
Wallet management	✅ Yes	❌ No
Exchange rates	✅ Yes (BTCPay)	✅ Yes (Satoshi API)
Blockchain data	❌ No	✅ Yes (49 tools)
Node RPC	❌ No	✅ Yes (optional)
Merchant payments	✅ Only option	❌ No

btcpay-mcp is complementary to blockchain data servers like bitcoin-mcp. Use both for complete Bitcoin coverage: blockchain data from bitcoin-mcp, payment processing from btcpay-mcp.

Run Tests

pip install -e ".[dev]"
pytest tests/ -v

All 77 tests pass with mock-based testing (no BTCPay instance needed).

Technical Details

Python 3.10+ compatible
FastMCP SDK (official Anthropic MCP Python SDK)
Authentication: Bearer token via BTCPAY_API_KEY environment variable
Transport: stdio (for Claude Desktop, Cursor, VS Code, Windsurf, etc.)
Default testnet: Points to https://testnet.demo.btcpayserver.org by default

License

MIT

Reviews

No reviews yet

Be the first to review this server!

More Developer Tools MCP Servers

Git

Free

by Modelcontextprotocol · Developer Tools

Read, search, and manipulate Git repositories programmatically

Toleno

Free

by Toleno · Developer Tools

Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.

mcp-creator-python

Free

by mcp-marketplace · Developer Tools

Create, build, and publish Python MCP servers to PyPI — conversationally.

Btcpay MCP Server

About

Security Report

Permissions Required

Documentation

btcpay-mcp

Quick Start

Claude Desktop

Claude Code

Cursor / VS Code

Manual / pip install

Tools

Top Use Cases

Configuration

Creating a BTCPay API Key

API Endpoints

How This Differs from Other Bitcoin MCP Servers

Run Tests

Technical Details

License

Reviews

No reviews yet

More Developer Tools MCP Servers

Git

Toleno

mcp-creator-python

MarkItDown

mcp-creator-typescript

FinAgent