whmcs-bridge-mcp

An MCP (Model Context Protocol) server for the WHMCS External API — built for safe production use, not just convenience.

Read-only by default. Write actions are opt-in per domain. Billing and destructive actions require a two-step confirmation. Secrets, card data, and PII are redacted before results ever reach the model. The server detects your WHMCS version at startup and warns on unsupported installs.

Tested against the WHMCS 8.12.x and 9.0.x External API contract (action names and parameters are unchanged across that range).

Install

npm install -g whmcs-bridge-mcp
# or run without installing:
npx whmcs-bridge-mcp

Claude Desktop / Claude Code

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["-y", "whmcs-bridge-mcp"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs-install.example.com/includes/api.php",
        "WHMCS_API_IDENTIFIER": "your-api-identifier",
        "WHMCS_API_SECRET": "your-api-secret",
        "WHMCS_MCP_MODE": "readonly"
      }
    }
  }
}

From source

git clone https://github.com/peguesj/whmcs-mcp.git
cd whmcs-mcp
npm install
npm run build
cp .env.example .env   # fill in your own values — never commit real credentials
node dist/index.js

Related MCP server: whm-mcp-server

Quickstart

1. In WHMCS admin, create a dedicated API Credential (Setup → Staff Management → Manage API Credentials, or the legacy API user under System Settings) and, if your WHMCS version supports it, an API Role scoped to only the actions you intend to expose. Least-privilege first — see SECURITY.md for a recommended role recipe.

2. Set WHMCS_API_URL, WHMCS_API_IDENTIFIER, and WHMCS_API_SECRET (see .env.example).

3. Leave WHMCS_MCP_MODE unset or readonly for your first run. Confirm the server starts and system_get_details reports your WHMCS version.

4. Add domains you need with WHMCS_MCP_ENABLE_DOMAINS (defaults to all domains, filtered by mode/tier).

5. Only set WHMCS_MCP_MODE=write or full once you have reviewed Safety model below and understand what each mode exposes.

Safety model

Every tool has a tier:

And every deployment has a mode, set via WHMCS_MCP_MODE:

WHMCS_MCP_ENABLE_DOMAINS (comma-separated: tickets,clients,products,invoices,domains,orders,system) further narrows which domains' tools are registered at all, independent of mode.

flowchart LR
    subgraph Tiers
        R[read]
        W[write]
        B[billing]
        D[destructive]
    end
    subgraph Modes
        RO[readonly<br/>default]
        WM[write]
        FM[full]
    end
    RO -->|advertises| R
    WM -->|advertises| R
    WM -->|advertises| W
    WM -->|advertises, confirm required| D
    FM -->|advertises| R
    FM -->|advertises| W
    FM -->|advertises, confirm required| B
    FM -->|advertises, confirm required| D

Two-step confirmation (billing and destructive tiers): the first call to a gated tool returns a human-readable preview plus a short-lived, single-use confirmToken (HMAC-signed, 5-minute TTL, bound to the tool name and a hash of its arguments). The caller must repeat the call with that exact token to execute. Every mutating tool also accepts dryRun: true, which returns the same preview and makes no network call at all — no token needed, no state changed.

Redaction runs on every response and on error messages before they leave the process: API secrets, session/access keys, stored passwords, full card and bank account numbers, CVV, and EPP transfer codes are always stripped. Email, phone, and address fields are redacted when WHMCS_MCP_REDACT_PII=true (the recommended default for any shared or logged transcript).

Operator policy note: this project ships with the invoice-mutating tools (billing_create_invoice, billing_update_invoice, billing_add_payment, billing_apply_credit, billing_capture_payment) in the billing tier specifically so an operator can enforce "no agent writes to WHMCS invoices" by simply never setting WHMCS_MCP_MODE=full. Do not enable full mode in a deployment where invoice mutation must stay human-only.

See SECURITY.md for the full threat model and the recommended least-privilege WHMCS API role.

Example: a billing/destructive call through an agent harness

The sequence below shows a harness-driven agent (any orchestrator that spawns subagents against this MCP server — the example uses an ecc-style agent config) walking a billing-tier tool through the confirm-token flow. The agent never mutates state on the first call; it only mutates after echoing back the exact confirmToken it was handed.

sequenceDiagram
    participant Agent as Harness agent (ecc)
    participant MCP as whmcs-bridge-mcp
    participant WHMCS as WHMCS External API

    Agent->>MCP: billing_apply_credit(clientid, amount, description)
    Note over MCP: tier=billing, no confirmToken present
    MCP-->>Agent: preview + confirmToken (5m TTL, single-use)
    Agent->>Agent: surface preview to operator / policy check
    Agent->>MCP: billing_apply_credit(..., confirmToken)
    Note over MCP: token verified, matches tool+args hash
    MCP->>WHMCS: AddCredit
    WHMCS-->>MCP: result=success
    MCP-->>Agent: structuredContent (redacted)

Registering the server under an ecc-family harness config looks the same as any other MCP client — add it once per project or globally, then reference its tools by name from an agent definition:

// .claude/settings.json (or wherever your harness reads MCP server config)
{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["-y", "whmcs-bridge-mcp"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs-install.example.com/includes/api.php",
        "WHMCS_API_IDENTIFIER": "your-api-identifier",
        "WHMCS_API_SECRET": "your-api-secret",
        "WHMCS_MCP_MODE": "readonly"
      }
    }
  }
}

<!-- an ecc-style agent definition scoping which tools it may call -->
---
name: whmcs-ticket-triage
description: Read-only ticket triage. Never enables write/billing/destructive tools.
tools: mcp__whmcs__tickets_list, mcp__whmcs__tickets_get, mcp__whmcs__tickets_get_predefined_replies
model: haiku
---

Keep write/billing/destructive tools out of a read-only agent's tools: allowlist even when the server itself is running in a more permissive mode elsewhere — the mode/domain gates above are the server's own defense-in-depth, not a substitute for scoping what each agent can reach.

Configuration

Full details, including per-tool minimum API-role permissions: docs/configuration.md. WHMCS 8.x/9.x compatibility notes: docs/version-compatibility.md.

Tools

The full generated tool reference — every tool, its tier, its WHMCS action, and its parameters — lives in docs/tools.md (regenerated from the zod schemas via npm run gen:docs, also published as site/data/tools.json for the marketing site's tool catalog).

At a glance, tools are grouped by domain, mirroring src/tools/:

• system — system_get_details (version discovery), system_get_stats, system_get_activity_log, system_get_admin_details, system_get_todo_items, system_get_email_templates, system_send_email, system_get_payment_methods, system_get_currencies, system_log_activity, plus the whmcs_raw_call escape hatch (full mode only, allowlisted actions, confirm-gated).

• tickets — list/get/create/reply/update/note/merge/delete tickets, attachments, counts, departments, statuses, predefined replies.

• clients — list/get/create/update/close clients, contacts, client emails, client groups.

• products — product/promotion lookups, client services and addons, service and addon updates, module lifecycle (create/suspend/unsuspend/terminate/change-package), product/config-option upgrades.

• invoices — invoice list/get/create/update, payments, credits, transactions, billable items, saved pay methods, and quotes (list/create/update/send).

• domains — client domain list, WHOIS lookup and availability, nameservers, locking, renew/register/transfer, TLD pricing.

• orders — order list/create/accept/pending/cancel/fraud/delete, order statuses.

Example call (MCP tool invocation shown as JSON-RPC-style params):

{
  "name": "tickets_list",
  "arguments": { "status": "Open", "limitnum": 25 }
}

Example of a confirm-gated mutation:

// 1. First call — preview only, no network mutation
{ "name": "tickets_delete", "arguments": { "ticketid": 4821 } }
// -> { "preview": "Delete ticket #4821 (subject: ...) — irreversible", "confirmToken": "eyJ..." }

// 2. Second call — echoes the token to execute
{ "name": "tickets_delete", "arguments": { "ticketid": 4821, "confirmToken": "eyJ..." } }

Versioning

This repo tags atomically: every commit (via a post-commit git hook in .githooks/) bumps package.json's MINOR version and creates an annotated vX.Y.0 tag on the resulting version-bump commit. Hooks wire themselves up automatically on npm install (via the prepare script setting git config core.hooksPath .githooks); no manual setup is needed after cloning.

Development

npm install
npm run typecheck     # tsc --noEmit
npm run lint
npm test              # vitest against an in-process mock WHMCS server (test/mock-whmcs-server.ts)
npm run gen:docs       # regenerate docs/tools.md and site/data/tools.json from the tool registry
npm run screenshots    # Playwright captures against MCP Inspector + the mock server, for site/assets/screenshots
npm run pack:check     # npm pack --dry-run

The mock WHMCS server serves synthetic fixture data only (test/fixtures/) — screenshots and tests never touch a real WHMCS instance or real client data.

Docker

docker build -t whmcs-mcp .
docker run --rm -i \
  -e WHMCS_API_URL -e WHMCS_API_IDENTIFIER -e WHMCS_API_SECRET \
  -e WHMCS_MCP_MODE=readonly \
  whmcs-mcp

The image is a multi-stage build onto a distroless Node runtime, running as a non-root user, with stdio as the default transport.

Security

See SECURITY.md for the threat model, the recommended least-privilege WHMCS API role, the billing-tier policy, and how to report a vulnerability.

Acknowledgments

Several WHMCS MCP servers already existed before this one; each contributed an idea worth borrowing:

This project differentiates on safety posture (tiered mode matrix, confirm-token flow, deep redaction), license (MIT, no paid tier), typed schemas (one zod schema per WHMCS action, not a generic dispatcher), version awareness (runtime WhmcsDetails check), and an extensible custom-action layer for operator-defined tools outside the built-in domain set.

License

MIT © Jeremiah Pegues