whmcs-mcp-server

WHMCS MCP Server

Automate your hosting business with AI agents. Connect Claude, Cursor, Windsurf, or any MCP-compatible AI to your WHMCS installation.

73 tools covering clients, tickets, products, invoices, orders, domains, and system health.

Why This Exists

Hosting providers spend 20-50 hours/week on manual WHMCS tasks — triaging tickets, provisioning accounts, chasing invoices, managing domains. AI agents connected through the Model Context Protocol can automate these workflows natively.

This server gives AI agents direct, secure access to your entire WHMCS installation through 73 purpose-built tools. Built by a hosting agency, for hosting agencies.

Quick Start

1. Install

npm install -g whmcs-mcp-server

Or clone the repo:

git clone https://github.com/not-sure-w/whmcs-mcp-server.git
cd whmcs-mcp-server
npm install

2. Configure

Create a .env file with your WHMCS credentials:

WHMCS_BASE_URL=https://your-whmcs-domain.com
WHMCS_IDENTIFIER=your_api_identifier
WHMCS_SECRET=your_api_secret

Get these from your WHMCS admin: Setup > Staff Management > API Credentials. Ensure your server IP is whitelisted under Setup > General Settings > Security.

3. Connect

Add the server to your AI tool's MCP configuration (see Integration below), then ask your agent to manage WHMCS directly.

Features

Category	Tools	Key Capabilities
Clients (9)	list, get, add, update, delete, users	Full client lifecycle, user management
Tickets (12)	list, get, open, reply, notes, canned replies	Ticket triage, responses, internal notes, departments
Products (11)	provision, suspend, unsuspend, terminate, upgrade	Service provisioning, module operations, package changes
Invoices (11)	create, update, payments, transactions, credits	Invoice management, payment recording, client credits
Orders (9)	add, accept, pending, cancel, fraud check	Order processing, fraud detection
Domains (11)	register, transfer, renew, nameservers, WHOIS	Full domain lifecycle, lock management, TLD pricing
Health (10)	health check, stats, activity log, email, projects	System monitoring, reporting, email, project management

Total: 73 tools covering the full WHMCS API.

New Features

Billing Analytics Tools

Advanced invoice analysis capabilities for billing operations:

Tool	Description
whmcs_find_invoice_gaps	Detects missing invoice numbers in sequences, helping identify gaps caused by failed payments, manual deletions, or system issues
whmcs_analyze_pending_invoices	Analyzes pending invoices to identify patterns, age distribution, and recommends collection actions

Operation Modes

Control server behavior with three operation modes:

Mode	Environment Variable	Behavior
read_only	WHMCS_OPERATION_MODE=read_only	Blocks all write operations (create, update, delete). Returns error for any mutation attempt.
simulate	WHMCS_OPERATION_MODE=simulate	Logs all operations but does not execute them against WHMCS. Useful for testing AI workflows safely.
full (default)	WHMCS_OPERATION_MODE=full	Normal operation — executes all operations against WHMCS

# Example: Run in simulate mode for testing
WHMCS_OPERATION_MODE=simulate

Client Access Mode

Multi-tenant isolation for service providers managing multiple WHMCS clients:

Variable	Description
WHMCS_CLIENT_ACCESS_MODE	Enable client isolation (enabled or disabled)
MCP_ALLOWED_CLIENT_IDS	Comma-separated list of allowed client IDs

When enabled, tools that support client filtering will only return data for the specified clients.

# Example: Restrict to specific clients
WHMCS_CLIENT_ACCESS_MODE=enabled
MCP_ALLOWED_CLIENT_IDS=1,5,12,18

IP Allowlist

Restrict server access by IP/CIDR:

WHMCS_IP_ALLOWLIST=192.168.1.0/24,10.0.0.5/32

Requests from IPs not in the allowlist are rejected before any operation executes.

Ops Playbook Resource

AI agent guidance via the ops-playbook:// MCP resource. Provides operational playbooks, troubleshooting guides, and best practices for common WHMCS tasks.

# Access via MCP resource
ops-playbook://ticket-escalation
ops-playbook://invoice-collection
ops-playbook://service-provisioning

Security

This server implements defense-in-depth security:

• HTTPS enforcement — API credentials only sent over encrypted connections
• Response sanitization — Passwords, credit card data, and sensitive fields automatically redacted
• Credential masking — Identifiers masked in logs (e.g., abc***xyz), never logged in full
• Startup credential validation — Server tests each credential's permissions on startup and reports scope
• Confirmation for destructive ops — Delete and terminate operations require explicit confirmation tokens
• Input validation — All parameters validated with Zod schemas (email format, dates, enums, length limits)
• Request timeouts — 30-second timeout prevents hung connections
• Audit logging — All tool invocations logged to stderr with sensitive params redacted

Access Control

Three layers of access control, from simple to granular:

Mode	Description
Single-key (default)	One credential set for all tools
Multi-key	Separate credentials for readonly/standard/admin tool tiers
Read-only mode	Set WHMCS_MCP_READONLY=true to register only read-only tools

Fine-grained tool allowlisting/denylisting via WHMCS_MCP_ALLOWED_TOOLS and WHMCS_MCP_DENIED_TOOLS.

For the full security guide including credential validation output, warning interpretation, and API role scoping, see the Security Configuration section below.

Safety Features

This server includes additional safety mechanisms for production AI agent operations:

Idempotency Protection

Prevents duplicate operations from accidental re-execution. Destructive operations (delete, terminate, cancel) are cached for 60 seconds to detect and block repeated calls.

WHMCS_IDEMPOTENCY_CACHE_TTL=60  # seconds (default)

Circuit Breaker

State machine that tracks WHMCS API failures and automatically "trips" to prevent cascading failures. When the circuit is open, operations fail fast without hammering a failing API.

State	Behavior
closed	Normal operation
open	Operations fail immediately
half-open	Test requests allowed to check recovery

WHMCS_CIRCUIT_BREAKER_THRESHOLD=5   # failures before opening
WHMCS_CIRCUIT_BREAKER_TIMEOUT=30    # seconds before half-open

Per-Tool Rate Limits

Sliding window rate limiting per tool to prevent abuse:

WHMCS_RATE_LIMIT_WINDOW=60      # window in seconds
WHMCS_RATE_LIMIT_MAX=10         # max requests per window per tool

Audit Logging

Structured JSON logging with automatic sensitive data redaction:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "tool": "whmcs_delete_client",
  "params": { "client_id": "***REDACTED***" },
  "user": "api_user",
  "result": "success"
}

Large Refund Threshold Warnings

Alerts when processing refunds exceeding configured thresholds:

WHMCS_REFUND_WARNING_THRESHOLD=1000  # USD amount

Unpaid Invoice Check Before Termination

Automatically checks for unpaid invoices before allowing service termination:

WHMCS_CHECK_UNPAID_BEFORE_TERMINATE=true

Failed Capture Detection

Detects and logs failed payment captures to identify billing issues:

WHMCS_DETECT_FAILED_CAPTURES=true

Integration

OpenCode

Add to your opencode.json:

{
  "mcp": {
    "whmcs": {
      "type": "local",
      "command": ["npx", "whmcs-mcp-server"],
      "env": {
        "WHMCS_BASE_URL": "https://your-whmcs-domain.com",
        "WHMCS_IDENTIFIER": "your_api_identifier",
        "WHMCS_SECRET": "your_api_secret"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["whmcs-mcp-server"],
      "env": {
        "WHMCS_BASE_URL": "https://your-whmcs-domain.com",
        "WHMCS_IDENTIFIER": "your_api_identifier",
        "WHMCS_SECRET": "your_api_secret"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json or MCP settings:

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["whmcs-mcp-server"],
      "env": {
        "WHMCS_BASE_URL": "https://your-whmcs-domain.com",
        "WHMCS_IDENTIFIER": "your_api_identifier",
        "WHMCS_SECRET": "your_api_secret"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["whmcs-mcp-server"],
      "env": {
        "WHMCS_BASE_URL": "https://your-whmcs-domain.com",
        "WHMCS_IDENTIFIER": "your_api_identifier",
        "WHMCS_SECRET": "your_api_secret"
      }
    }
  }
}

Generic Stdio (any MCP client)

{
  "command": "npx",
  "args": ["whmcs-mcp-server"],
  "env": {
    "WHMCS_BASE_URL": "https://your-whmcs-domain.com",
    "WHMCS_IDENTIFIER": "your_api_identifier",
    "WHMCS_SECRET": "your_api_secret"
  }
}

Docker

docker compose up

Development with hot-reload:

docker compose --profile dev up

Use Cases

Auto-reply to Tier 1 support tickets — Agent reads new tickets, matches against canned replies, and responds with solutions for common issues like password resets and billing questions.

Bulk suspend accounts with overdue invoices — Agent queries unpaid invoices older than 30 days, identifies associated services, and suspends them with a documented reason.

Renew all domains expiring this month — Agent lists client domains, filters by expiry date, and processes renewals for domains the client has opted to auto-renew.

Generate daily health report — Agent pulls system stats, open ticket counts, pending orders, and activity log entries, then summarizes the day's operational status.

Provision new accounts from orders — Agent accepts pending orders, provisions the associated services, and sends welcome emails to new clients.

Chase overdue invoices — Agent identifies overdue invoices, checks client history, and sends reminder emails with payment links.

Development

npm run dev          # Hot-reload development
npm run build        # Build for production
npm run start        # Run production build
npm run test         # Run tests
npm run test:watch   # Watch mode
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint
npm run lint:fix     # Fix lint issues
npm run format       # Format code with Prettier
npm run validate     # Run all checks (typecheck + lint + format + test)

Project Structure

src/
├── index.ts          # MCP server entry point (v1.0.0)
├── client.ts         # WHMCS API client (auth, HTTP, sanitization)
├── config.ts         # Environment config, credential loading, tool access
├── utils.ts          # Shared utilities (audit logging)
└── tools/
    ├── clients.ts    # Client & user management (9 tools)
    ├── tickets.ts    # Support ticket management (12 tools)
    ├── products.ts   # Product & service operations (11 tools)
    ├── invoices.ts   # Invoice & payment tools (11 tools)
    ├── orders.ts     # Order management (9 tools)
    ├── domains.ts    # Domain lifecycle tools (11 tools)
    └── health.ts     # System health & misc (10 tools)

Security Configuration

Credential Validation on Startup

The server automatically validates credentials on startup by testing read access, probing permission scope (read, write, delete, tickets, orders, invoices, products, domains, admin), and reporting results to stderr with masked identifiers. Validation is non-blocking — warnings are logged but the server still starts.

Interpreting Validation Warnings

Warning	Meaning	Action
Read access FAILED	Cannot read from WHMCS API	Check identifier/secret, verify IP whitelist
Credential can write but cannot delete	Partial write permissions	Expected for restricted roles; verify if delete tools are needed
Credential lacks admin-level access	WhmcsDetails API call failed	Some health/stats tools may not work
denied on specific scopes	Permission not granted for that area	Create a more permissive API role if needed

Recommended API Roles

Role	Permissions
Read-only	View Clients, View Tickets, View Products, View Invoices, View Orders, View Domains
Support	Read-only + Manage Tickets, Add Client Notes
Billing	Read-only + Manage Invoices, Manage Orders
Admin	Full API access (all permissions)

Multi-Key Mode (Defense-in-Depth)

Use separate credentials for different tool tiers. If any multi-key variable is set, single-key mode is automatically disabled.

WHMCS_BASE_URL=https://your-whmcs-domain.com
WHMCS_READONLY_IDENTIFIER=readonly_api_id
WHMCS_READONLY_SECRET=readonly_api_secret
WHMCS_STANDARD_IDENTIFIER=standard_api_id
WHMCS_STANDARD_SECRET=standard_api_secret
WHMCS_ADMIN_IDENTIFIER=admin_api_id
WHMCS_ADMIN_SECRET=admin_api_secret

Credential Set	Tools	Risk if Compromised
Read-only	list/get tools	Attacker can only read data
Standard	create/update tools	Attacker can modify but not delete
Admin	delete/terminate/fraud tools	Full destructive access

Tool Allowlisting / Denylisting

# Only these tools will be registered
WHMCS_MCP_ALLOWED_TOOLS=whmcs_list_clients,whmcs_get_ticket,whmcs_health_check

# These tools will be excluded
WHMCS_MCP_DENIED_TOOLS=whmcs_delete_client,whmcs_delete_ticket,whmcs_module_terminate

WHMCS_MCP_ALLOWED_TOOLS takes precedence. If both are set, only the allowlist is used.

Tool Role Reference

Role	Description	Example Tools
readonly	Safe read-only operations	whmcs_list_clients, whmcs_get_ticket
standard	Create/update (non-destructive)	whmcs_add_client, whmcs_open_ticket
admin	Destructive/irreversible	whmcs_delete_client, whmcs_module_terminate

Environment Variables

# Required
WHMCS_BASE_URL=https://your-whmcs-domain.com

# Single-key mode (default)
WHMCS_IDENTIFIER=your_api_identifier
WHMCS_SECRET=your_api_secret

# OR Multi-key mode (optional, overrides single-key)
# WHMCS_READONLY_IDENTIFIER=readonly_api_id
# WHMCS_READONLY_SECRET=readonly_api_secret
# WHMCS_STANDARD_IDENTIFIER=standard_api_id
# WHMCS_STANDARD_SECRET=standard_api_secret
# WHMCS_ADMIN_IDENTIFIER=admin_api_id
# WHMCS_ADMIN_SECRET=admin_api_secret

# Access control (optional)
# WHMCS_MCP_READONLY=false
# WHMCS_MCP_ALLOWED_TOOLS=whmcs_list_clients,whmcs_get_ticket
# WHMCS_MCP_DENIED_TOOLS=whmcs_delete_client

# Operation mode (optional)
# WHMCS_OPERATION_MODE=full        # full (default), read_only, simulate

# Client access mode (optional)
# WHMCS_CLIENT_ACCESS_MODE=enabled
# MCP_ALLOWED_CLIENT_IDS=1,5,12

# IP allowlist (optional)
# WHMCS_IP_ALLOWLIST=192.168.1.0/24,10.0.0.5/32

# Safety features (optional)
# WHMCS_IDEMPOTENCY_CACHE_TTL=60
# WHMCS_CIRCUIT_BREAKER_THRESHOLD=5
# WHMCS_CIRCUIT_BREAKER_TIMEOUT=30
# WHMCS_RATE_LIMIT_WINDOW=60
# WHMCS_RATE_LIMIT_MAX=10
# WHMCS_REFUND_WARNING_THRESHOLD=1000
# WHMCS_CHECK_UNPAID_BEFORE_TERMINATE=true
# WHMCS_DETECT_FAILED_CAPTURES=true

WHMCS_BASE_URL must use https://. HTTP connections are rejected.

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Run npm run validate to ensure all checks pass
• Commit and push
• Open a Pull Request

License

ISC License — see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Support development: Buy me a coffee

Consulting & Custom Development

Need help integrating WHMCS with AI agents or want custom MCP tools built for your setup?

• GitHub: Contact via Issues