@billingserv/mcp-server

BillingServ MCP Server

Connect AI assistants like Claude, ChatGPT (Codex), Cursor, and Gemini to your BillingServ account.

This is a read-only MCP server for the BillingServ API. It lets an AI assistant look up customers, invoices, orders, packages, and reports in your BillingServ installation — and answer questions 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?"

Read-only by design. The server only calls an allowlist of safe GET endpoints. It never sends POST, PUT, PATCH, or DELETE requests, so an AI assistant can never modify your billing data.

Requirements

• Node.js 20 or newer (npx is included with Node.js)
• A BillingServ API key

Configuration

Every client setup below uses the same three environment variables:

Variable	Required	Description
BILLINGSERV_API_BASE_URL	Yes	Your BillingServ API v2 base URL, e.g. https://billing.example.com/api/v2
BILLINGSERV_API_KEY	Yes	Your BillingServ API key
BILLINGSERV_TIMEOUT_MS	No	Request timeout in milliseconds (default 15000)

Tip: create a dedicated API key for AI use with the minimum permissions needed. Even though this server is read-only, a narrowly scoped key limits what the assistant can see.

Setup

Claude Code

Run 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

Then restart Claude Code and ask it something like "List my BillingServ endpoints."

Claude Desktop

Open Settings → Developer → Edit Config and add this to claude_desktop_config.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. You should see 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"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio servers works. Use:

• Command: npx
• Arguments: -y @billingserv/mcp-server
• Environment: the variables from Configuration

Tools

The server exposes two tools:

billingserv_list_endpoints

Lists every BillingServ endpoint this server can call, with descriptions and required parameters. Assistants use this to discover what data is available.

billingserv_get

Calls one allowlisted BillingServ API v2 GET endpoint.

{
  "endpoint": "customer/get",
  "query": { "id": 123 }
}

Endpoints with placeholders in the path take a path object:

{
  "endpoint": "meter/{customer_id}/get/{order_id}",
  "path": { "customer_id": 123, "order_id": 456 }
}

Available endpoints

Area	Endpoints
Customers	customer/lists, customer/get, customer/get-credit
Invoices	invoice/lists, invoice/get-payment-method, invoice/get-transactions
Orders	order/get-orders, order/get-orders-by-status, order/available-package-changes, order/preview-package-change, order/check-fraud
Packages	package/lists, package/get, package/show, package/get-by-customer, package/group/lists, package/group/get, package/option/lists, package/option/get
Reports	report/annual-sales, report/revenue-trend, report/sales-by-staff, report/sales-by-customer, report/package-leaderboard, report/customer-receipt, report/customer-credit, report/customer-invoice, report/customer-debt, report/login-history
Marketing	marketing/lists, marketing/get-discount
Usage metering	meter/{customer_id}/get/{order_id}
Settings	setting/invoice, setting/lists-staff, setting/get-staff, setting/lists-tax-zone, setting/get-tax-zone, setting/lists-tax-class, setting/get-tax-class
VPN	vpn/branding/get, vpn/servers/list
Geography	country/lists, country/get, county/lists-by-country
Modules	module/get-module-configuration

Security

• Only allowlisted GET endpoints can be called — the endpoint list is compiled into the server and validated on every request.
• State-changing routes (including state-changing GET routes such as password reset) are deliberately excluded.
• Your API key is read from the environment and sent only to the base URL you configure. It is never logged or returned in tool output.

Development

git clone https://github.com/billingserv/billingserv-mcp-server.git
cd billingserv-mcp-server
npm install
npm run build

BILLINGSERV_API_BASE_URL="https://billing.example.com/api/v2" \
BILLINGSERV_API_KEY="your_api_key" \
npm start

Or put the variables in a local .env file (gitignored) and run npm run start:dev.

License

MIT