# mcp

The BillingServ MCP server lets your assistant read customers, invoices and orders from your billing system. Useful when the answer has to come from live records.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: BillingServ
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/BillingServ/MCP
- Updated: 2026-08-24
- HTML: https://affpapa.org/en/nevibecode/mcp/billingserv-mcp

## What it does

The server talks to BillingServ API v2 and exposes three tools. `billingserv_list_endpoints` shows which endpoints exist and what parameters they take. `billingserv_get` calls an allowed GET endpoint, while `billingserv_create` writes through POST endpoints and also handles software licence activation and validation.

Reads and writes sit in separate tools on purpose. You can leave lookups open and still put an approval step on `billingserv_create` in the client. Only a fixed allowlist of endpoints is reachable, and it is checked on every request. Deleting records and taking payments are left out, so the assistant cannot go that far.

You need Node.js 20 or newer, which ships `npx`, plus a BillingServ API key. Three environment variables drive the config: `BILLINGSERV_API_BASE_URL` pointing at your API v2 base, `BILLINGSERV_API_KEY`, and an optional `BILLINGSERV_TIMEOUT_MS` set to 15000 by default. A wrong base URL or a missing key means the server simply will not serve queries.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `BILLINGSERV_API_BASE_URL`, `BILLINGSERV_API_KEY`, `BILLINGSERV_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env BILLINGSERV_API_BASE_URL=<BILLINGSERV_API_BASE_URL> --env BILLINGSERV_API_KEY=<BILLINGSERV_API_KEY> --env BILLINGSERV_TIMEOUT_MS=<BILLINGSERV_TIMEOUT_MS> --transport stdio billingserv-mcp -- npx -y @billingserv/mcp-server
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add billingserv-mcp --env BILLINGSERV_API_BASE_URL=<BILLINGSERV_API_BASE_URL> --env BILLINGSERV_API_KEY=<BILLINGSERV_API_KEY> --env BILLINGSERV_TIMEOUT_MS=<BILLINGSERV_TIMEOUT_MS> -- npx -y @billingserv/mcp-server
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "billingserv-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@billingserv/mcp-server"
            ],
            "env": {
                "BILLINGSERV_API_BASE_URL": "<BILLINGSERV_API_BASE_URL>",
                "BILLINGSERV_API_KEY": "<BILLINGSERV_API_KEY>",
                "BILLINGSERV_TIMEOUT_MS": "<BILLINGSERV_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "billingserv-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@billingserv/mcp-server"
            ],
            "env": {
                "BILLINGSERV_API_BASE_URL": "<BILLINGSERV_API_BASE_URL>",
                "BILLINGSERV_API_KEY": "<BILLINGSERV_API_KEY>",
                "BILLINGSERV_TIMEOUT_MS": "<BILLINGSERV_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e BILLINGSERV_API_BASE_URL=<BILLINGSERV_API_BASE_URL> -e BILLINGSERV_API_KEY=<BILLINGSERV_API_KEY> -e BILLINGSERV_TIMEOUT_MS=<BILLINGSERV_TIMEOUT_MS> billingserv-mcp npx -y @billingserv/mcp-server
```
Replace <…> with your own values

## When to use it
- list customers with unpaid invoices for the month
- read the revenue trend for the year
- check which packages a customer owns and what they can switch to
- validate a software licence activation
- open a ticket or draft an invoice from the chat

## Example prompts
- Which customers have unpaid invoices this month?
- Show the revenue trend for this year from BillingServ reports
- Validate this licence and create a ticket if it fails

## Similar
- [mcp-vindi](https://affpapa.org/en/nevibecode/mcp/mcp-vindi.md) — MCP server · ★ 274
- [mcp-tiny](https://affpapa.org/en/nevibecode/mcp/mcp-tiny.md) — MCP server · ★ 274
- [fortnox](https://affpapa.org/en/nevibecode/mcp/fortnox.md) — MCP server · ★ 45
- [Xero](https://affpapa.org/en/nevibecode/mcp/xero.md) — MCP server · ★ 13
- [quote-to-cash](https://affpapa.org/en/nevibecode/skills/quote-to-cash.md) — skill · 1700 installs

## Other versions with the same name
- [mcp · kubeshark](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — ★ 12110
- [mcp · butterbase-ai](https://affpapa.org/en/nevibecode/mcp/butterbase-ai-mcp.md) — ★ 3031
- [mcp · medplum](https://affpapa.org/en/nevibecode/mcp/mcp.md) — ★ 2766
- [mcp · sceneview](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — ★ 1349
- [mcp · buoy-gg](https://affpapa.org/en/nevibecode/mcp/buoy-gg-mcp.md) — ★ 691

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md