io.github.danchev/spherepay

Official

by danchev · Python

SpherePay

Manage SpherePay customers, bank accounts, wallets, and transfers from Claude.

Manage SpherePay customers, bank accounts, wallets, and transfers.

README.md4 KBView on GitHub

SpherePay MCP Server

A Model Context Protocol server for the SpherePay payment platform. Manage customers, bank accounts, wallets, transfers, virtual accounts, webhooks, and CCTP off-ramps directly from Claude.

Features

24 curated tools — 9 workflow tools for multi-step operations, 15 read-only tools for instant lookups
Automatic retries with exponential backoff and rate limit handling
Idempotency for transfers — duplicate requests are safely deduplicated
PII redaction in logs — account numbers, routing numbers, and personal data are never logged
Input validation at the tool boundary — IDs, currencies, networks, and amounts are validated before any API call
Desktop Extension (.mcpb) for one-click Claude Desktop installation

Tools

Workflow Tools

Tool	Description
`onboard_customer`	Create a customer (individual or business) and generate TOS/KYC verification links
`verify_customer`	Two-step verification: send OTP, then verify with face recognition
`setup_funding`	Create a bank account (USD/EUR) or crypto wallet for a customer
`execute_transfer`	Transfer money between funding instruments with automatic idempotency
`onboard_business_rep`	Create and verify a business representative
`setup_virtual_account`	Create a virtual account for automatic fiat-to-stablecoin conversion
`setup_offloader_wallet`	Create an offloader wallet for stablecoin-to-fiat off-ramp
`create_webhook`	Subscribe to event notifications via HTTPS webhooks
`submit_cctp_offramp`	Submit a CCTP burn transaction for cross-chain off-ramp redemption

Read-Only Tools

Tool	Description
`get_customer` / `list_customers`	Retrieve customer details and verification status
`get_transfer` / `list_transfers`	Retrieve transfers with status, filter by customer/status/type
`get_bank_account` / `list_bank_accounts`	Retrieve bank account details, filter by customer
`get_wallet` / `list_wallets`	Retrieve wallet details, filter by customer
`get_virtual_account` / `list_virtual_accounts`	Retrieve virtual account details and deposit instructions
`list_virtual_account_transfers`	List deposits and conversions for a virtual account
`get_offloader_wallet` / `list_offloader_wallets`	Retrieve offloader wallet details and off-ramp config
`get_webhook`	Retrieve webhook details and delivery status
`get_event`	Retrieve event details and webhook delivery records

Supported Currencies and Networks

Currency	Type
`usd`, `eur`	Fiat
`usdc`, `usdt`, `eurc`	Stablecoin

Network	Type
`ach`, `wire`, `sepa`	Fiat rails
`ethereum`, `polygon`, `sol`, `base`, `arbitrum`, `tron`, `avalanche`, `optimism`	Blockchain

Installation

Prerequisites

Python 3.12+
A SpherePay API key (get one here)

Claude Desktop (stdio)

Add to your Claude Desktop config (claude_desktop_config.json):

json

{
  "mcpServers": {
    "spherepay": {
      "command": "uvx",
      "args": ["spherepay-mcp"],
      "env": {
        "SPHEREPAY_BASE_URL": "https://api.sandbox.spherepay.co",
        "SPHEREPAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Desktop Extension

Download the latest .mcpb file from GitHub Releases and double-click to install in Claude Desktop.

Standalone

bash

git clone https://github.com/danchev/spherepay-mcp.git
cd spherepay-mcp
uv sync
uv run spherepay-mcp

Configuration

Variable	Required	Default	Description
`SPHEREPAY_API_KEY`	Yes	—	Your SpherePay API key (Bearer token)
`SPHEREPAY_BASE_URL`	No	`https://api.sandbox.spherepay.co`	API base URL. Use `https://api.spherepay.co` for production
`SPHEREPAY_TIMEOUT`	No	`30`	Request timeout in seconds
`SPHEREPAY_MAX_RETRIES`	No	`3`	Max retry attempts for transient failures (429, 5xx)

License

AGPL-3.0 License. See LICENSE for details.

Install

Configuration

Environment variables

SPHEREPAY_API_KEYrequiredsecret

Your SpherePay API key (Bearer token). Get one at https://dashboard.spherepay.co

SPHEREPAY_BASE_URL

API base URL. Use https://api.sandbox.spherepay.co for testing or https://api.spherepay.co for production.

SPHEREPAY_TIMEOUT

Request timeout in seconds (default: 30)

SPHEREPAY_MAX_RETRIES

Maximum retry attempts for transient failures (default: 3)

claude_desktop_config.json

{
  "mcpServers": {
    "spherepay": {
      "command": "uvx",
      "args": [
        "spherepay-mcp"
      ],
      "env": {
        "SPHEREPAY_API_KEY": "<YOUR_SPHEREPAY_API_KEY>",
        "SPHEREPAY_BASE_URL": "<YOUR_SPHEREPAY_BASE_URL>",
        "SPHEREPAY_TIMEOUT": "<YOUR_SPHEREPAY_TIMEOUT>",
        "SPHEREPAY_MAX_RETRIES": "<YOUR_SPHEREPAY_MAX_RETRIES>"
      }
    }
  }
}