{
  "markdown": "# BillingServ MCP Server\n\nThe [BillingServ MCP server](https://www.billingserv.com/mcp/) connects AI assistants like Claude, ChatGPT (Codex), Cursor, and Gemini to your BillingServ account.\n\nIt provides [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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:\n\n- \"Which customers have unpaid invoices this month?\"\n- \"Show me the revenue trend for this year.\"\n- \"What packages does customer 123 have, and what could they upgrade to?\"\n- \"Validate this software license activation.\"\n\nAnd your assistant answers from live billing data instead of guessing.\n\nYou can also ask it to do things: raise a support ticket, create an order, draft an invoice, or add a note to a customer.\n\n**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.\n\n## Requirements\n\n- [Node.js](https://nodejs.org) 20 or newer (`npx` comes with it)\n- A BillingServ API key\n\n## Configuration\n\nEvery client setup below uses the same three environment variables:\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `BILLINGSERV_API_BASE_URL` | Yes | Your BillingServ API v2 base URL, e.g. `https://billing.example.com/api/v2` |\n| `BILLINGSERV_API_KEY` | Yes | Your BillingServ API key |\n| `BILLINGSERV_TIMEOUT_MS` | No | Request timeout in milliseconds (default `15000`) |\n\n## Setup\n\nFind your client below, drop in your URL and API key, and you're done.\n\n### Claude Code\n\nOne command:\n\n```bash\nclaude mcp add billingserv \\\n  --env BILLINGSERV_API_BASE_URL=\"https://billing.example.com/api/v2\" \\\n  --env BILLINGSERV_API_KEY=\"your_api_key\" \\\n  -- npx -y @billingserv/mcp-server\n```\n\nRestart Claude Code and try asking it to list your BillingServ endpoints.\n\n### Claude Desktop\n\nOpen **Settings → Developer → Edit Config** and add this to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"billingserv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@billingserv/mcp-server\"],\n      \"env\": {\n        \"BILLINGSERV_API_BASE_URL\": \"https://billing.example.com/api/v2\",\n        \"BILLINGSERV_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop and look for the `billingserv` tools under the tools icon.\n\n### OpenAI Codex CLI\n\nAdd this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.billingserv]\ncommand = \"npx\"\nargs = [\"-y\", \"@billingserv/mcp-server\"]\n\n[mcp_servers.billingserv.env]\nBILLINGSERV_API_BASE_URL = \"https://billing.example.com/api/v2\"\nBILLINGSERV_API_KEY = \"your_api_key\"\n```\n\n### Cursor\n\nAdd this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"billingserv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@billingserv/mcp-server\"],\n      \"env\": {\n        \"BILLINGSERV_API_BASE_URL\": \"https://billing.example.com/api/v2\",\n        \"BILLINGSERV_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nAdd this to `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"billingserv\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@billingserv/mcp-server\"],\n      \"env\": {\n        \"BILLINGSERV_API_BASE_URL\": \"https://billing.example.com/api/v2\",\n        \"BILLINGSERV_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### Gemini CLI\n\nAdd this to `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"billingserv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@billingserv/mcp-server\"],\n      \"env\": {\n        \"BILLINGSERV_API_BASE_URL\": \"https://billing.example.com/api/v2\",\n        \"BILLINGSERV_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### Other MCP clients\n\nAny MCP client that supports stdio servers will work. Point it at:\n\n- **Command:** `npx`\n- **Arguments:** `-y @billingserv/mcp-server`\n- **Environment:** the variables from [Configuration](#configuration)\n\n## Tools\n\nThe server gives your assistant three tools:\n\n### `billingserv_list_endpoints`\n\nLists 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.\n\n### `billingserv_get`\n\nCalls one allowlisted BillingServ API v2 `GET` endpoint.\n\n```json\n{\n  \"endpoint\": \"customer/get\",\n  \"query\": { \"id\": 123 }\n}\n```\n\nEndpoints with placeholders in the path take a `path` object instead:\n\n```json\n{\n  \"endpoint\": \"meter/{customer_id}/get/{order_id}\",\n  \"path\": { \"customer_id\": 123, \"order_id\": 456 }\n}\n```\n\n### `billingserv_create`\n\nCreates 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.\n\n```json\n{\n  \"endpoint\": \"ticket/create\",\n  \"body\": {\n    \"subject\": \"Question about my last invoice\",\n    \"user_id\": 123,\n    \"message\": \"Customer called about a duplicate charge.\",\n    \"support_department\": \"billing\"\n  }\n}\n```\n\n## Available endpoints\n\n| Area | Endpoints |\n| --- | --- |\n| Customers | `customer/lists`, `customer/get`, `customer/get-credit` |\n| Invoices | `invoice/lists`, `invoice/get-payment-method`, `invoice/get-transactions` |\n| Orders | `order/get-orders`, `order/get-orders-by-status`, `order/available-package-changes`, `order/preview-package-change`, `order/check-fraud` |\n| Packages | `package/lists`, `package/get`, `package/show`, `package/get-by-customer`, `package/group/lists`, `package/group/get`, `package/option/lists`, `package/option/get` |\n| 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` |\n| Support tickets | `ticket/lists`, `ticket/get` |\n| Marketing | `marketing/lists`, `marketing/get-discount` |\n| Usage metering | `meter/{customer_id}/get/{order_id}` |\n| 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` |\n| VPN | `vpn/branding/get`, `vpn/servers/list` |\n| Geography | `country/lists`, `country/get`, `county/lists-by-country` |\n| Modules | `module/get-module-configuration` |\n\nAnd these write endpoints, available through `billingserv_create`:\n\n| Area | Endpoints |\n| --- | --- |\n| Support tickets | `ticket/create`, `ticket/reply`, `ticket/update` |\n| Orders | `order/add-order` |\n| Customers | `customer/create`, `customer/add-note` |\n| Invoices | `invoice/create-invoice`, `invoice/create-quote`, `invoice/send-invoice`, `invoice/send-invoice-reminder` |\n| Packages | `package/create`, `package/update`, `package/group/create`, `package/group/update`, `package/option/create`, `package/option/update` |\n| Marketing | `marketing/create-discount` |\n| Licensing | `license/activate`, `license/validate`, `license/deactivate` |\n\nPackage creation and updates support the API's `digital_delivery` object for download policies and software licensing controls. For example:\n\n```json\n{\n  \"endpoint\": \"package/update\",\n  \"body\": {\n    \"id\": 12,\n    \"group_id\": 3,\n    \"name\": \"Desktop App\",\n    \"digital_delivery\": {\n      \"delivery_enabled\": true,\n      \"download_policy\": \"cap_limited\",\n      \"max_downloads\": 5,\n      \"licensing_enabled\": true,\n      \"activation_limit\": 2,\n      \"offline_cache_minutes\": 60\n    }\n  }\n}\n```\n\n## Security\n\n- The endpoint allowlist is compiled into the server and checked on every request. Only allowlisted endpoints can be called.\n- Sensitive routes like password reset are deliberately left out.\n- 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.\n- 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.\n\n## Development\n\n```bash\ngit clone https://github.com/billingserv/billingserv-mcp-server.git\ncd billingserv-mcp-server\nnpm install\nnpm run build\n\nBILLINGSERV_API_BASE_URL=\"https://billing.example.com/api/v2\" \\\nBILLINGSERV_API_KEY=\"your_api_key\" \\\nnpm start\n```\n\nOr put the variables in a local `.env` file (gitignored) and run `npm run start:dev`.\n\n## License\n\nMIT\n",
  "bytes": 8700,
  "sha": "f5ab53c4906cd9709a219466c0814f402597d2d769ddfadd2d20f74cff00abf8",
  "repo_slug": "billingserv/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_billingserv_mcp_03226a86/readme"
}