whmcs-mcp-server

v1.3.1

Published

2 months ago

Model Context Protocol server for WHMCS — automate your hosting business with AI agents. 60+ tools for client, ticket, product, invoice, order, and domain management.

0High
0Medium
0Low

whyyvz

whmcs mcp model-context-protocol ai ai-agents hosting hosting-automation automation billing whmcs-api llm-tools mcp-server opencode

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