READMEmaster

Voltage Payments MCP Server

This repository contains a Model Context Protocol (MCP) server that provides a programmatic interface to the Voltage Payments API. The server dynamically exposes API endpoints as callable tools, allowing for seamless integration with AI assistants and other systems.

Warning

This work was completed during FOSS Friday at Voltage and released as open source for educational purposes. It should go without saying, (but hey, this is the internet, so who knows) but this can have unexpected side effects. If you run this MCP server with an API key with real money, it can be used to make real payments. Putting that kind of power into the hands of an LLM is #reckless. I think it's kind of awesome, but know there could be surprises.

Use at your own risk, etc.

Setup and Configuration

Environment Variables

The server requires the following environment variables to be set:

API_KEY: Your Voltage API key
ORGANIZATION_ID: Your Voltage organization ID (UUID format)
ENVIRONMENT_ID: Your Voltage environment ID (UUID format)
BASE_URL: The base URL for the Voltage API (e.g., https://api.voltage.cloud)

Configuring `claude_desktop_config.json`

To use this MCP server with Claude Desktop, you'll need to properly configure the claude_desktop_config.json file. This file tells Claude Desktop how to connect to your MCP server and what tools are available.

Location of the Config File

The claude_desktop_config.json file is typically located in:

macOS: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json
Windows: %APPDATA%\Claude Desktop\claude_desktop_config.json
Linux: ~/.config/Claude Desktop/claude_desktop_config.json

Configuration Structure

Here's how to structure your claude_desktop_config.json file:

{
  "mcpServers": {
    "voltage-payments-python": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/payment-mcp/server.py"
      ],
      "env": {
        "API_KEY": "your-api-key",
        "ORGANIZATION_ID": "organization-uuid",
        "ENVIRONMENT_ID": "environment-uuid",
        "BASE_URL": "https://backend.voltage.cloud"
      }
    }
  }
}

Available Tools

The MCP server exposes the following tools for interacting with the Voltage Payments API:

Wallet Operations

get_all_wallets: Get all wallets for the organization
create_wallet: Create a new wallet in the organization
get_wallet: Get a specific wallet by its ID
delete_wallet: Delete a specific wallet by its ID
get_wallet_ledger_as_user: Get the ledger for a specific wallet

Payment Operations

get_payments: Get a list of payments with optional filtering
check_payment_status: Check the status of a payment by its ID
generate_bolt11_invoice: Generate a BOLT11 invoice for receiving a payment
pay_bolt11_invoice: Pay a BOLT11 invoice

Example Usage

Below is a screenshot showing the Voltage Payments MCP server in action with Claude:

Claude using Voltage Payments MCP

Running the Server Manually

If you prefer to run the server manually rather than through Claude Desktop's auto-start feature:

# Set environment variables
export API_KEY=your_api_key
export ORGANIZATION_ID=your_org_id
export ENVIRONMENT_ID=your_env_id
export BASE_URL=https://api.voltage.cloud

# Run the server
python server.py

Security Considerations

Store your API keys and other sensitive information securely.
Do not commit your claude_desktop_config.json file with actual API keys to version control.
Consider using environment variables or a secure secrets manager instead of hardcoding credentials.

voltage-payments-mcp