Provides automatic detection and parsing of Xero contact, invoice, and payment IDs from GoCardless payment metadata, enabling integration between GoCardless payments and Xero accounting records.
GoCardless MCP Server
A Model Context Protocol (MCP) server for GoCardless API integration, enabling AI assistants to interact with GoCardless payment data.
Features
This MCP server provides tools to:
Customers: List, get, and create customers
Payments: List, get, and create payments
Mandates: List and get mandates
Subscriptions: List and get subscriptions (including combined details with customer/mandate)
Payouts: List payouts
Xero Integration: Automatic detection and parsing of Xero contact/invoice/payment IDs from metadata
Limitations
Read-only recommended: While customer and payment creation are supported, read-only API tokens are recommended for most use cases
No update operations: Existing records cannot be modified
No cancellation: Subscriptions, mandates, and payments cannot be cancelled through this server
Installation
Using uvx (Recommended for Claude Code/Cursor)
No installation required - uvx will automatically fetch and run the package:
Configure in your MCP settings (see configuration examples below).
Using pipx
Using pip
Local Development
Configuration
Environment Variables
You'll need to configure these environment variables:
GOCARDLESS_ACCESS_TOKEN
(required): Your GoCardless API access tokenGOCARDLESS_ENVIRONMENT
(optional): Eithersandbox
orlive
(defaults tosandbox
)
Get a GoCardless Access Token:
Sign up for a GoCardless sandbox account
Navigate to Developers > API tokens
Create a new access token
Copy the token for use in configuration
Setup for Different AI Tools
Claude Desktop
Claude Desktop is the easiest way to get started with MCP servers.
Configuration file location:
MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%/Claude/claude_desktop_config.json
Add this configuration:
After configuration:
Restart Claude Desktop
Look for the 🔨 (hammer) icon in the bottom-right corner
Click it to verify the GoCardless server is connected
Start asking questions like "Show me my recent GoCardless customers"
Claude Code
Claude Code works best with uvx for automatic package management.
Method 1: Using uvx (Recommended)
Method 2: Edit Configuration File Directly
Edit ~/.claude.json
:
After configuration:
Restart Claude Code
Verify with:
claude mcp list
The GoCardless server should appear in the list
Cursor IDE
Cursor works best with uvx for automatic package management.
Project-specific configuration (recommended):
Create .cursor/mcp.json
in your project root:
Global configuration (available in all projects):
Create ~/.cursor/mcp.json
:
After configuration:
Restart Cursor
Open the MCP settings page to verify the server is connected
The Composer Agent will automatically use GoCardless tools when relevant
Other MCP Clients
For any MCP client that supports stdio transport:
The server communicates via JSON-RPC over stdin/stdout, so it won't produce output when run directly.
Data Hierarchy
GoCardless data follows this hierarchy:
Customer (CU*) → Mandate (MD*) → Subscription (SB*) / Payment (PM*)
Mandates authorize recurring payments. Subscriptions generate recurring payments automatically.
Available Tools
Customer Tools
list_customers
: List all customers (optional limit parameter)get_customer
: Get a specific customer by IDcreate_customer
: Create a new customer (requires email, optional given_name, family_name, company_name)
Payment Tools
list_payments
: List payments (optional limit, status, subscription, mandate filters)get_payment
: Get a specific payment by ID (includes links to mandate/subscription)create_payment
: Create a new payment (requires amount, currency, mandate_id, optional description)
Mandate Tools
list_mandates
: List mandates (optional limit and customer parameters)get_mandate
: Get a specific mandate by ID (includes link to customer)
Subscription Tools
list_subscriptions
: List subscriptions (optional limit and status parameters)get_subscription
: Get a specific subscription by ID (includes link to mandate)get_subscription_details
: Get complete subscription info including mandate and customer in one call
Payout Tools
list_payouts
: List payouts (optional limit parameter)
Usage Examples
Once configured in Claude Desktop, you can ask:
"Show me my recent GoCardless customers"
"Get details for customer CU123"
"Create a new customer with email test@example.com"
"List all pending payments"
"Show me the details of payment PM123"
Development & Testing
Testing with MCP Inspector
The MCP Inspector provides an interactive web interface to test your server:
This will:
Start the inspector on
http://localhost:6274
Open your browser automatically
Allow you to set environment variables in the UI
Interactively test all available tools
In the Inspector:
Set your
GOCARDLESS_ACCESS_TOKEN
in the environment variables sectionSet
GOCARDLESS_ENVIRONMENT
tosandbox
Browse available tools on the left sidebar
Click any tool to see its schema
Fill in parameters and click "Run" to test
Testing with a Python Client
Create a test script to programmatically test the server:
Running Tests
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
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.
Tools
Enables AI assistants to interact with GoCardless payment data, providing tools to manage customers, payments, mandates, subscriptions, and payouts. Includes Xero integration support for automatic parsing of metadata.