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):
{
"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
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
MIT
1 maintainer
Metadata
1 maintainer
Release files for spherepay-mcp 0.0.1.post0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spherepay_mcp-0.0.1.post0.tar.gz | 20.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spherepay_mcp-0.0.1.post0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 50.6 kB
Release files / spherepay_mcp-0.0.1.post0.tar.gz
| Download URL | spherepay_mcp-0.0.1.post0.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c51fb118da0c9d1d97c710de49782135cd41618777ac73e86d00e335fba48207
|
|
BLAKE2b-256 checksum How to use checksums |
c40826be70fdcd89c5cc11962b0496395efc3c9882ddfe640a896d5481636298
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"openSUSE Tumbleweed","version":"20260304","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / spherepay_mcp-0.0.1.post0-py3-none-any.whl
| Download URL | spherepay_mcp-0.0.1.post0-py3-none-any.whl |
|---|---|
| Size | 30.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2ebe83bc2568e7c4cdf8166109283deaebbdace6b551c3bb9ae0e024f586c7f
|
|
BLAKE2b-256 checksum How to use checksums |
56065dd4ff4e77e2de4f94e23f8aecace0c310b5d1652301b7a32567cb318b8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"openSUSE Tumbleweed","version":"20260304","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
