@billium/mcp

@billium/mcp is the official Billium Model Context Protocol server. It lets AI agents — Claude Code, Claude Desktop, Cursor, and any other MCP host — manage your Billium account in natural language:

"Create a $49.99 invoice for order #1234 and give me the checkout link." "List my last 10 invoices and tell me which are still awaiting payment." "Add a webhook to https://api.myshop.com/billium that fires on invoice.paid."

The server runs locally and talks directly to the Billium API over HTTPS — it's a thin layer over @billium/node, so it inherits the same behavior and guarantees.

Requirements

• Node.js ≥ 18.
• A Billium secret API key (sk_...) and your merchant ID (mer_...), from the dashboard under Settings → Developer → API keys. See Authentication.

Configuration

The server reads three environment variables:

Connect your client

claude mcp add billium \
  --env BILLIUM_API_KEY=sk_your_key \
  --env BILLIUM_MERCHANT_ID=mer_your_id \
  -- npx -y @billium/mcp

{
  "mcpServers": {
    "billium": {
      "command": "npx",
      "args": ["-y", "@billium/mcp"],
      "env": {
        "BILLIUM_API_KEY": "sk_your_key",
        "BILLIUM_MERCHANT_ID": "mer_your_id"
      }
    }
  }
}

{
  "mcpServers": {
    "billium": {
      "command": "npx",
      "args": ["-y", "@billium/mcp"],
      "env": {
        "BILLIUM_API_KEY": "sk_your_key",
        "BILLIUM_MERCHANT_ID": "mer_your_id"
      }
    }
  }
}

Tools

The server exposes 23 tools across five resources. Inputs are validated before each call, and create_invoice always sends an idempotency key (generated if you don't pass one), so a retried call never creates a duplicate invoice.

Invoices

• create_invoice — create a crypto payment invoice
• get_invoice — fetch an invoice with status, payments, and timeline
• list_invoices — list invoices with pagination and search
• cancel_invoice — cancel an unpaid invoice

Customers

• list_customers — list customers with pagination and search
• get_customer — fetch a customer by ID
• get_customer_stats — revenue and invoice stats for a customer
• update_customer — update a customer's name, address, or phone

Products

• create_product, get_product, list_products, update_product, delete_product

Wallets

• list_wallets, get_wallet, create_wallet, update_wallet, delete_wallet

Webhooks

• create_webhook, list_webhooks, update_webhook, delete_webhook, ping_webhook

How it works

• The server runs locally on your machine and talks directly to the Billium API over HTTPS. Your secret key never leaves your environment.
• Settlement is non-custodial — payments go straight to your wallet; Billium never holds funds.
• Because it wraps @billium/node, the same resource shapes, scopes (sk_ vs pk_), and error semantics apply. See the SDK reference for response details.