SpherePay
Manage SpherePay customers, bank accounts, wallets, and transfers from Claude.
Open source Open in the app JSON README (API)
About
Manage SpherePay customers, bank accounts, wallets, and transfers from Claude.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- danchev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.0.1
- Last push
- 2026-03-07T04:31:05Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-08-29 03:02:40
- Updated
- 2026-08-29 03:02:40
- Origin id
io.github.danchev/spherepay
README
# SpherePay MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) server for the [SpherePay](https://spherepay.co) 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](https://spherepay.co/dashboard))
### 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](https://github.com/danchev/spherepay-mcp/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](LICENSE) for details.
<!-- mcp-name: io.github.danchev/spherepay -->