home / mcp / btcpayserver model context protocol server (beta)

BTCPayServer Model Context Protocol Server (Beta)

A MCP server enabling BTCPayServer integration with payment processing, store management, user administration, and webhook handling via a full API surface.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "abhijay007-btcpayserver-mcp": {
      "command": "node",
      "args": [
        "path/to/btcpayserver-mcp/dist/index.js"
      ],
      "env": {
        "BTCPAY_API_KEY": "your_api_key_here",
        "BTCPAY_BASE_URL": "https://your-btcpay-instance.com",
        "BTCPAY_STORE_ID": "your_default_store_id"
      }
    }
  }
}

You are ready to work with the BTCPayServer MCP server, a compact, extensible bridge that enables you to interact with BTCPayServer APIs through a Model Context Protocol interface. It centralizes payment processing, store management, user administration, webhook handling, and more, providing a consistent programmatic way to integrate BTCPayServer functionality into your applications or assistants.

How to use

Start by connecting your MCP client to the BTCPayServer MCP server. You will first discover what methods are available, then learn what parameters are required for a chosen operation, and finally execute the action you need. To explore, use the built-in discovery flow to list available services and methods. To perform a task, prepare the required parameters and submit the request through the MCP interface. This approach helps you perform typical actions such as creating invoices, managing stores, handling webhooks, and coordinating user access without interacting with BTCPayServer’s raw REST API directly.

Typical usage pattern in practical terms: discover what you can do, inspect what inputs are required for a specific operation, then perform the operation with the appropriate parameters. You can perform common tasks like creating invoices, managing stores, enabling webhooks, and configuring payout methods using the MCP server as your single integration point.

How to install

Follow these steps to set up the BTCPayServer MCP server locally and ready to run in your environment.

git clone <repository-url>
cd btcpayserver-mcp
npm install
npm run build
npm start

Configuration and running notes

The MCP server requires particular environment variables to connect to your BTCPayServer instance. You will provide the base URL, an API key with appropriate permissions, and an optional default store ID. These values are used by the MCP server to authenticate and direct requests to the correct BTCPayServer instance and store.

Environment variables you should configure include the base URL of your BTCPayServer, your API key, and an optional default store ID for operations. You can set these in a .env file at the project root or export them in your shell session.

For local development and debugging, you can run the server in development mode if your workflow supports it, and use a debugging tool to inspect requests and responses as you experiment with API calls.

Security and best practices

Protect your API keys by never committing them to version control. Use secure environment variable management and rotate keys periodically. Apply least-privilege principles when assigning API key permissions, and use webhook secrets to verify incoming webhook payloads. Ensure your BTCPayServer instance uses HTTPS to protect data in transit.

Maintain robust access control for users and client applications that interact with the MCP server. Regularly review permissions and monitor for anomalous activity in your BTCPayServer environment.

Troubleshooting

If you encounter configuration or API errors, verify that environment variables are correctly set and that the BTCPayServer API key has the required permissions for the operations you intend to perform. Ensure network connectivity to your BTCPayServer instance and that the API endpoint is reachable via HTTPS.

For authentication issues, confirm that the API key is valid, not expired, and that the associated permissions cover the actions you are attempting. If webhooks are involved, check webhook secrets and configure the correct callback URLs in BTCPayServer.

Notes and considerations

This MCP server provides a consolidated interface to BTCPayServer services, enabling easier automation and integration with assistive tools. Keep dependencies up to date and align your usage with the BTCPayServer API version that your instance supports.

Available tools

get_service_info

Discover available services and methods exposed by the MCP server for exploration and discovery.

get_method_info

Retrieve detailed parameter requirements for a specific service method to prepare requests accurately.

btcpay_request

Execute API calls against BTCPayServer through the MCP bridge to perform operations such as creating invoices or managing stores.