Mcp MCP Server

BillingServ MCP Server

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

This is an MCP server for the BillingServ API. Once it's set up, your AI assistant can look up customers, invoices, orders, packages, 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?"

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

Safe by design. The server only calls a fixed allowlist of BillingServ endpoints, checked on every request. Today that covers lookups and reports, with support for creating and updating records on the roadmap.

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 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 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"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio servers will work. Point it at:

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

Tools

The server gives your assistant two tools:

billingserv_list_endpoints

Lists every BillingServ endpoint the server can call, along with descriptions, required parameters, and valid values. Assistants usually call this first to see 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 instead:

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

Available endpoints

Security

• The endpoint allowlist is compiled into the server and checked on every request. Only allowlisted endpoints can be called.
• Sensitive routes like password reset are deliberately left out.
• Your API key is read from the environment and only ever sent to the base URL you configure. It's never logged or included 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