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.

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.

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

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

whmcs-mcp-server

Quick Install