MCP server

BillingServ MCP Server

The BillingServ MCP server connects AI assistants like Claude, ChatGPT (Codex), Cursor, and Gemini to your BillingServ account.

It provides Model Context Protocol (MCP) access to the BillingServ API. Once it's set up, your AI assistant can look up customers, invoices, orders, packages, software licenses, and reports straight from your BillingServ installation. Ask things like:

• "Which customers have unpaid invoices this month?"
• "Show me the revenue trend for this year."
• "What packages does customer 123 have, and what could they upgrade to?"
• "Validate this software license activation."

And your assistant answers from live billing data instead of guessing.

You can also ask it to do things: raise a support ticket, create an order, draft an invoice, or add a note to a customer.

Safe by design. The server only calls a fixed allowlist of BillingServ endpoints, checked on every request. Reads and writes are separate tools, so you can let your AI look things up freely while requiring approval for anything that creates or changes records. Deleting records and capturing payments are deliberately not available.

Requirements

• Node.js 20 or newer (npx comes with it)
• A BillingServ API key

Configuration

Every client setup below uses the same three environment variables:

Setup

Find your client below, drop in your URL and API key, and you're done.

Claude Code

One command:

claude mcp add billingserv \
  --env BILLINGSERV_API_BASE_URL="https://billing.example.com/api/v2" \
  --env BILLINGSERV_API_KEY="your_api_key" \
  -- npx -y @billingserv/mcp-server

Restart Claude Code and try asking it to list your BillingServ endpoints.

Claude Desktop

Open Settings → Developer → Edit Config and add this to claudedesktopconfig.json:

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Claude Desktop and look for the billingserv tools under the tools icon.

OpenAI Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.billingserv]
command = "npx"
args = ["-y", "@billingserv/mcp-server"]

[mcp_servers.billingserv.env]
BILLINGSERV_API_BASE_URL = "https://billing.example.com/api/v2"
BILLINGSERV_API_KEY = "your_api_key"

Cursor

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "billingserv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

Gemini CLI

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

Shortened. The full README is on GitHub.