Skip to main content
Glama
BillingServ

BillingServ MCP

Official
by BillingServ
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

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

Related MCP server: bt-panel-mcp-server

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)

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

billingserv_create

Creates or updates records through an allowlisted set of POST endpoints. It also activates, validates, and deactivates software licenses. This is the tool to gate behind approval in your MCP client if you want a confirmation step before anything changes.

{
  "endpoint": "ticket/create",
  "body": {
    "subject": "Question about my last invoice",
    "user_id": 123,
    "message": "Customer called about a duplicate charge.",
    "support_department": "billing"
  }
}

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

Support tickets

ticket/lists, ticket/get

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

And these write endpoints, available through billingserv_create:

Area

Endpoints

Support tickets

ticket/create, ticket/reply, ticket/update

Orders

order/add-order

Customers

customer/create, customer/add-note

Invoices

invoice/create-invoice, invoice/create-quote, invoice/send-invoice, invoice/send-invoice-reminder

Packages

package/create, package/update, package/group/create, package/group/update, package/option/create, package/option/update

Marketing

marketing/create-discount

Licensing

license/activate, license/validate, license/deactivate

Package creation and updates support the API's digital_delivery object for download policies and software licensing controls. For example:

{
  "endpoint": "package/update",
  "body": {
    "id": 12,
    "group_id": 3,
    "name": "Desktop App",
    "digital_delivery": {
      "delivery_enabled": true,
      "download_policy": "cap_limited",
      "max_downloads": 5,
      "licensing_enabled": true,
      "activation_limit": 2,
      "offline_cache_minutes": 60
    }
  }
}

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.

  • Licensing endpoints use the submitted license key as their credential, as required by the API, so the BillingServ bearer token is not sent to those routes.

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

Available Tools

3 tools
billingserv_createCreate or update BillingServ recordsA

Create or update records in BillingServ: support tickets and ticket replies, orders, customers, customer notes, invoices, quotes, discounts, packages, package groups, and package options. Can also send an invoice or payment reminder to a customer by email. This tool changes real billing data and can email customers, so confirm the details with the user before calling it. Only allowlisted endpoints can be called; deleting records and capturing payments are not available through this server.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYesJSON body for the endpoint. See billingserv_list_endpoints for each endpoint's required and optional fields. Dotted field names such as cycle.cycle, record.item, or options.id are parallel arrays inside a nested object: pass them either as dotted keys ({"cycle.cycle": [5], "cycle.price": [10]}) or as a nested object ({"cycle": {"cycle": [5], "price": [10]}}); dotted keys are expanded to the nested form before sending.
endpointYesAllowlisted BillingServ write endpoint, relative to /api/v2. All write endpoints use POST.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It warns that the tool changes real billing data and can email customers, requiring user confirmation. It also notes that only allowlisted endpoints are callable and that deletions/payments are unavailable. This discloses key behavioral traits, though it could mention whether it returns created records or errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (three sentences) and front-loaded: first sentence states purpose and lists record types, second adds email capability, third warns about behavior and limitations. Every sentence adds useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description doesn't explain return values, but it references billingserv_list_endpoints for detail on required/optional fields. It covers input parameters well and provides necessary caveats. For a creation tool, missing return details is a minor gap, but overall completeness is good for agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining dotted field names and how to pass them (nested objects vs dotted keys), and references billingserv_list_endpoints for per-endpoint field details. This goes beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title and description clearly state the tool creates or updates various BillingServ record types and can send emails. It distinguishes itself from sibling tools (billingserv_get, billingserv_list_endpoints) which are read/list operations. The description is specific about the resource and action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool (create/update records, send reminders) and when not to use it (deleting records, capturing payments not available). It advises confirming details with the user before calling, providing clear usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

billingserv_getQuery live BillingServ billing dataA

Fetch live billing data from the BillingServ API: customers, invoices (including unpaid and overdue), payment methods, transactions, orders, subscriptions, packages, discounts, usage meters, tax and staff settings, and sales/revenue reports. Use this for any question about billing, invoices, customers, orders, or revenue. Only allowlisted endpoints can be called.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoPath parameter values for endpoints with placeholders, such as customer_id and order_id.
queryNoQuery string parameters to pass to the BillingServ API endpoint.
endpointYesAllowlisted BillingServ API endpoint path, relative to /api/v2.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must bear the burden of transparency. It states 'Fetch live billing data' implying read-only, but does not explicitly confirm no destructive side effects, authentication needs, or rate limits. Listing many endpoints gives some context, but behavioral details are insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the purpose and listing data types concisely. The second sentence adds usage guidance and a constraint. It is efficient, though the list of data types is somewhat long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not explain return values or structure for the many endpoints. It covers what data can be fetched but lacks details on output format. For a tool with numerous endpoints, more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific information beyond the schema; it only provides high-level context about data types. The schema already describes 'path', 'query', and 'endpoint' adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches live billing data and lists many data types (customers, invoices, etc.). The verb 'fetch' and the context distinguish it from sibling tools 'billingserv_create' (write) and 'billingserv_list_endpoints' (endpoint listing), making its read-only purpose evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises 'Use this for any question about billing, invoices, customers, orders, or revenue,' providing clear context. It also notes the restriction 'Only allowlisted endpoints can be called.' However, it does not explicitly state when not to use it or directly compare with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

billingserv_list_endpointsList BillingServ endpointsA

List every BillingServ billing API endpoint available through this server, with descriptions and required parameters. Read endpoints cover customers, invoices, payments, orders, packages, discounts, support tickets, usage meters, settings, and sales/revenue reports. Write endpoints cover creating and updating tickets, orders, customers, invoices, quotes, discounts, packages, package groups, and package options, and sending invoices and payment reminders.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It accurately describes the tool as a read-only listing operation covering many areas. No destructive or hidden behaviors are implied. It is straightforward and complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first gives the primary action, second details categories. No wasted words, front-loaded with key information. Excellent structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description provides sufficient context about what endpoints are covered (read vs write). It could mention return format (e.g., list of endpoint objects) but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, so baseline is 4. The description does not add parameter info, but none is needed. Schema coverage is 100% (empty schema), so no deficiency.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all BillingServ API endpoints with descriptions and required parameters, and distinguishes itself from sibling tools 'billingserv_create' and 'billingserv_get' by being a discovery tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for exploring available endpoints before calling create or get, but does not explicitly state when to use or not use it. Sibling tool names provide context, but more direct guidance would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: create/update, fetch data, and list endpoints. No overlap or ambiguity between them.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern: billingserv_create, billingserv_get, billingserv_list_endpoints. Perfectly predictable.

Tool Count5/5

Three tools is well-scoped for a billing API server. Each tool serves a broad but necessary function, and the count feels appropriate for the domain.

Completeness4/5

The tools cover a wide range of billing operations: create/update many resources, fetch various data, and discover other endpoints. Minor gaps like delete and payment capture exist but are intentionally excluded.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BillingServ/MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server