Skip to main content
Glama

GoCardless MCP Server

by jmceleney

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:

uvx --from git+https://github.com/jmceleney/gocardless-mcp.git gocardless-mcp

Configure in your MCP settings (see configuration examples below).

Using pipx

pipx install git+https://github.com/jmceleney/gocardless-mcp.git

Using pip

pip install git+https://github.com/jmceleney/gocardless-mcp.git

Local Development

# Clone the repository git clone https://github.com/jmceleney/gocardless-mcp.git cd gocardless-mcp # Install in development mode pip install -e .

Configuration

Environment Variables

You'll need to configure these environment variables:

  • GOCARDLESS_ACCESS_TOKEN (required): Your GoCardless API access token

  • GOCARDLESS_ENVIRONMENT (optional): Either sandbox or live (defaults to sandbox)

Get a GoCardless Access Token:

  1. Sign up for a GoCardless sandbox account

  2. Navigate to Developers > API tokens

  3. Create a new access token

  4. 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:

{ "mcpServers": { "gocardless": { "command": "gocardless-mcp", "env": { "GOCARDLESS_ACCESS_TOKEN": "your_access_token_here", "GOCARDLESS_ENVIRONMENT": "sandbox" } } } }

After configuration:

  1. Restart Claude Desktop

  2. Look for the 🔨 (hammer) icon in the bottom-right corner

  3. Click it to verify the GoCardless server is connected

  4. 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)

claude mcp add gocardless \ --env GOCARDLESS_ACCESS_TOKEN=your_token_here \ --env GOCARDLESS_ENVIRONMENT=sandbox \ -- uvx --from git+https://github.com/jmceleney/gocardless-mcp.git gocardless-mcp

Method 2: Edit Configuration File Directly

Edit ~/.claude.json:

{ "mcpServers": { "gocardless": { "type": "stdio", "command": "uvx", "args": ["--from", "git+https://github.com/jmceleney/gocardless-mcp.git", "gocardless-mcp"], "env": { "GOCARDLESS_ACCESS_TOKEN": "your_access_token_here", "GOCARDLESS_ENVIRONMENT": "sandbox" } } } }

After configuration:

  1. Restart Claude Code

  2. Verify with: claude mcp list

  3. 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:

{ "mcpServers": { "gocardless": { "command": "uvx", "args": ["--from", "git+https://github.com/jmceleney/gocardless-mcp.git", "gocardless-mcp"], "env": { "GOCARDLESS_ACCESS_TOKEN": "your_access_token_here", "GOCARDLESS_ENVIRONMENT": "sandbox" } } } }

Global configuration (available in all projects):

Create ~/.cursor/mcp.json:

{ "mcpServers": { "gocardless": { "command": "uvx", "args": ["--from", "git+https://github.com/jmceleney/gocardless-mcp.git", "gocardless-mcp"], "env": { "GOCARDLESS_ACCESS_TOKEN": "your_access_token_here", "GOCARDLESS_ENVIRONMENT": "sandbox" } } } }

After configuration:

  1. Restart Cursor

  2. Open the MCP settings page to verify the server is connected

  3. The Composer Agent will automatically use GoCardless tools when relevant

Other MCP Clients

For any MCP client that supports stdio transport:

# Make sure environment variables are set export GOCARDLESS_ACCESS_TOKEN="your_token_here" export GOCARDLESS_ENVIRONMENT="sandbox" # Run the server gocardless-mcp

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 ID

  • create_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:

# Run the inspector (requires Node.js) npx @modelcontextprotocol/inspector gocardless-mcp

This will:

  1. Start the inspector on http://localhost:6274

  2. Open your browser automatically

  3. Allow you to set environment variables in the UI

  4. Interactively test all available tools

In the Inspector:

  1. Set your GOCARDLESS_ACCESS_TOKEN in the environment variables section

  2. Set GOCARDLESS_ENVIRONMENT to sandbox

  3. Browse available tools on the left sidebar

  4. Click any tool to see its schema

  5. Fill in parameters and click "Run" to test

Testing with a Python Client

Create a test script to programmatically test the server:

import asyncio import os from mcp.client.session import ClientSession from mcp.client.stdio import StdioServerParameters, stdio_client async def main(): server_params = StdioServerParameters( command="gocardless-mcp", env={ "GOCARDLESS_ACCESS_TOKEN": "your_sandbox_token", "GOCARDLESS_ENVIRONMENT": "sandbox" } ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # List available tools tools = await session.list_tools() print("Available tools:") for tool in tools.tools: print(f" - {tool.name}: {tool.description}") # Test a tool result = await session.call_tool("list_customers", {"limit": 5}) print("\nResult:", result) asyncio.run(main())

Running Tests

# Install development dependencies pip install -e ".[dev]" # Run tests (when implemented) pytest

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

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.

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.

  1. Features
    1. Limitations
      1. Installation
        1. Using uvx (Recommended for Claude Code/Cursor)
        2. Using pipx
        3. Using pip
        4. Local Development
      2. Configuration
        1. Environment Variables
      3. Setup for Different AI Tools
        1. Claude Desktop
        2. Claude Code
        3. Cursor IDE
        4. Other MCP Clients
      4. Data Hierarchy
        1. Available Tools
          1. Customer Tools
          2. Payment Tools
          3. Mandate Tools
          4. Subscription Tools
          5. Payout Tools
        2. Usage Examples
          1. Development & Testing
            1. Testing with MCP Inspector
            2. Testing with a Python Client
            3. Running Tests
          2. License
            1. Contributing

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmceleney/gocardless-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server