A
securityA
licenseA
qualityA server that enables interaction with Square's API via Goose, supporting queries for locations, customers, and more with context preservation and MCP-compliant responses.
Last updated -
5
MIT License
Provides comprehensive integration with BTCPayServer for Bitcoin payment processing, including invoice creation and management, payment request handling, Lightning Network operations, store management, webhook configuration, and user administration through BTCPayServer's complete API ecosystem.
BTCPayServer Model Context Protocol Server (Beta)
A comprehensive Model Context Protocol (MCP) server for BTCPayServer integration, providing tools for payment processing, store management, user administration, webhook handling and more with full API coverage.
Tool Reference
The BTCPayServer MCP Server provides a streamlined set of tools for interacting with BTCPayServer APIs:
Tool | Description | Primary Use |
| Discover methods available for a service | Exploration and discovery |
| Get detailed parameter requirements | Request preparation |
| Execute API calls to BTCPayServer | Performing operations |
Integration with AI Assistants
Claude Desktop Integration
For Claude Desktop integration, add this configuration to your claude_desktop_config.json:
{
"mcpServers": {
"btcpayserver-mcp": {
"command": "node",
"args": ["path/to/btcpayserver-mcp/dist/index.js"],
"env": {
"BTCPAY_BASE_URL": "https://your-btcpay-instance.com",
"BTCPAY_API_KEY": "your_api_key_here",
"BTCPAY_STORE_ID": "your_default_store_id"
}
}
}
}
Service Catalog
BTCPayServer MCP provides access to BTCPayServer's complete API ecosystem. Check out the BTCPayServer API Documentation for detailed information about each service:
Payment Services
Service | Description |
| Create, manage, and track Bitcoin invoices for payments |
| Create payment requests for donations or recurring billing |
| Manage internal Lightning Network operations |
| Store-level Lightning Network configurations |
| Lightning Address management and setup |
Store Management
Service | Description |
| Store creation, configuration, and management |
| Configure and manage store email settings and SMTP |
| Manage available payment methods for stores |
| Configure automated payout processing |
| Manage and process store payouts |
| Exchange rate configuration and management |
| Store user access and permissions management |
| Store wallet management and operations |
User & Access Management
Service | Description |
| User account management and administration |
| API key creation and permission management |
| OAuth and authorization flow management |
Integration & Automation
Service | Description |
| Real-time event notifications and webhook management |
| System notifications and alerts |
| BTCPayServer app integrations and plugins |
| Pull payment requests and refund management |
System
Service | Description |
| Server status, version, and configuration information |
Usage Pattern
For optimal interaction with the BTCPayServer API through MCP:
1. Discover: Use get_service_info to explore available methods
get_service_info(serviceName: "invoices")
2. Understand: Use get_method_info to learn parameter requirements
get_method_info(serviceName: "invoices", methodName: "create")
3. Execute: Use btcpay_request to perform the operation
btcpay_request(serviceName: "invoices", methodName: "create", parameters: {storeId: "your-store-id", amount: "10.00", currency: "USD"})
Installation
Clone this repository:
git clone <repository-url>
cd btcpayserver-mcp
Install dependencies:
npm install
Build the project:
npm run build
Configuration
The MCP server requires the following environment variables:
BTCPAY_BASE_URL- Your BTCPayServer instance URL (e.g.,https://btcpay.example.com)BTCPAY_API_KEY- Your BTCPayServer API keyBTCPAY_STORE_ID- (Optional) Default store ID for operations
Setting up BTCPayServer API Key
Log into your BTCPayServer instance
Go to Account → Manage Account → API Keys
Click Generate Key
Select the required permissions for your use case:
Store management:
btcpay.store.canmodifystoresettingsPayment requests:
btcpay.store.cancreateinvoiceUser management:
btcpay.user.canmodifyprofileWebhooks:
btcpay.store.webhooks.canmodifywebhooksetc..
Copy the generated API key
Environment Setup
Create a .env file in your project root:
BTCPAY_BASE_URL=https://your-btcpay-instance.com
BTCPAY_API_KEY=your_api_key_here
BTCPAY_STORE_ID=your_default_store_id
Or set environment variables directly:
export BTCPAY_BASE_URL=https://your-btcpay-instance.com
export BTCPAY_API_KEY=your_api_key_here
export BTCPAY_STORE_ID=your_default_store_id
Usage
Running the MCP Server
npm start
For development:
npm run dev
Development and Debugging
Using MCP Inspector: The MCP Inspector provides a visual interface for testing:
# Build the project
npm run build
# Start the inspector with the BTCPayServer MCP Server
npx @modelcontextprotocol/inspector node dist/index.js
Development Workflow:
Clone the repository
Install dependencies:
npm installStart development mode:
npm run buildRun the server:
node dist/index.jsTest your changes using the MCP Inspector
The MCP server provides comprehensive error handling:
Configuration Errors: Missing environment variables
API Errors: BTCPayServer API communication issues
Validation Errors: Invalid input parameters
Authentication Errors: Invalid or expired API keys
All errors are properly formatted and returned with descriptive messages.
Development
Project Structure
src/
├── index.ts # Main MCP server implementation
├── services/ # BTCPayServer service implementations
│ ├── base-service.ts # Base service class
│ ├── invoices.ts # Invoice management
│ ├── payment-requests.ts # Payment request handling
│ ├── stores.ts # Store management
│ ├── webhooks.ts # Webhook management
│ └── ... # Other service modules
├── utils/
│ └── btcpay-client.ts # BTCPayServer API client
└── types.ts # TypeScript type definitions
Building
npm run build
Running in Development
npm run dev
Security Considerations
API Key Security: Never commit API keys to version control
Environment Variables: Use secure environment variable management
Webhook Secrets: Always use webhook secrets for verification
HTTPS: Ensure BTCPayServer instance uses HTTPS
Permissions: Use principle of least privilege for API key permissions
BTCPayServer Compatibility
This MCP server is compatible with BTCPayServer v1.7.0 and later. It uses the official BTCPayServer REST API v1.
Contributing
Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
Check the BTCPayServer documentation
Review the API reference
Open an issue in this repository
Help us improve this MCP
Note: Some methods might not be working properly. Please help us by reporting requirements and making pull requests to improve them. Also, to keep it up with the latest API version, we need to continue updating it.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A comprehensive Model Context Protocol (MCP) server for BTCPayServer integration, providing tools for payment processing, store management, user administration, webhook handling and more with full API coverage.