Documentation
Everything you need to install, configure, and run WHMCS MCP Server. Full source on GitHub.
Prerequisites — WHMCS API Setup
Before running the installer you need a WHMCS API credential with the right permissions.
1. Create an API Role
In WHMCS Admin: Setup → Staff Management → API Roles → Add Role
Choose a permission preset based on how much access you want to grant the AI:
2. Set an API Access Key (recommended)
Add to your WHMCS configuration.php:
$api_access_key = 'your-secret-passphrase';Then set WHMCS_ACCESS_KEY to the same value in your .env. This lets the MCP server bypass IP restrictions, which is important since Docker container IPs can change on restart.
3. Create an API Credential
Setup → Staff Management → API Credentials → Generate New Credential
Select your API Role and copy the Identifier and Secret — you'll need these during setup.
Quick Start
Running in under 5 minutes:
Binary (no Docker required)
curl -fsSL https://daddar.io/whmcs-mcp/install.sh | sudo bashPrompts for your WHMCS credentials and license key, installs the binary to /usr/local/bin, and registers a systemd service.
Docker (recommended)
curl -fsSL https://daddar.io/whmcs-mcp/install-docker.sh | bashPrompts for credentials, writes .env, and starts the stack via Docker Compose.
Get a License
After checkout at daddar.io/store/ai-tools/whmcs-mcp, your license key appears in the client portal. Paste it into setup.sh when prompted, or set LICENSE_KEY in your .env.
No license? A 14-day free trial starts automatically on first run — no account needed.
86 WHMCS Tools
Every tool supports dryRun mode — see what would happen before taking action.
| Category | Tools |
|---|---|
| Clients | get_client list_clients add_client update_client get_client_details get_client_groups get_client_emails get_client_domains get_client_addons add_client_note |
| Invoices | get_invoice list_invoices create_invoice add_invoice_payment get_overdue_invoices get_transactions update_invoice |
| Orders | add_order get_orders accept_order cancel_order get_order_statuses fraud_order pending_order |
| Services | list_services update_service upgrade_product module_create module_suspend module_unsuspend module_terminate get_cancelled_packages |
| Tickets | get_ticket list_tickets open_ticket add_ticket_reply update_ticket get_support_departments add_ticket_note get_support_statuses get_ticket_counts get_ticket_predefined_categories |
| Quotes | get_quotes create_quote send_quote accept_quote update_quote delete_quote |
| Contacts | get_contacts add_contact update_contact |
| Credits | get_credits add_credit apply_credit |
| Billing | add_billable_item get_payment_methods get_currencies |
send_email get_email_templates | |
| Products | get_products get_product_groups |
| Domains | register_domain transfer_domain renew_domain get_domain_whois get_domain_nameservers update_domain_nameservers get_domain_lock_status update_domain_lock_status get_tld_pricing |
| Admin | get_admin_users get_staff_online get_whmcs_details log_activity get_activity_log |
| Affiliates | get_affiliates activate_affiliate |
| Promotions | get_promotions |
| Servers | get_servers module_change_password |
| System | get_health_status get_todo_items get_todo_item_statuses get_announcements get_registrars get_stats |
Authentication
WHMCS MCP always enforces authentication. Two modes work simultaneously:
Bearer Tokens (Cursor, local clients)
Generate a token with the built-in auth-cli:
docker exec -it whmcs-mcp node dist/scripts/auth-cli.js generate --name "Cursor" --scopes "mcp:read,mcp:write"Add to your Cursor MCP config:
{"mcpServers":{"whmcs":{"url":"https://your-mcp-url/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}OAuth 2.0 (Claude.ai, ChatGPT)
Set MCP_OAUTH_ADMIN_PASSWORD in your .env. Claude.ai and ChatGPT connect via Custom Connector — paste your MCP URL and complete the OAuth flow. PKCE + CIMD are fully supported.
MCP_AUTH_MODE and MCP_REQUIRE_AUTH are removed. Auth is always on. Remove these variables from your .env if present.
Webhook Push
Real-time event push from WHMCS to connected AI clients. When a WHMCS event fires (new ticket, new invoice, overdue payment), a PHP hook POSTs it to your running MCP instance, which broadcasts it to all active sessions as a notifications/message.
Supported events: InvoiceCreation, TicketOpen, TicketAddReply, OverdueInvoice, ClientAdd
Required env vars: WHMCS_WEBHOOK_SECRET on the MCP server; WHMCS_MCP_URL and WHMCS_MCP_WEBHOOK_SECRET on the WHMCS server.
Observability
- Prometheus metrics — request rates, latencies, error counts, WHMCS API performance. Scraped from
:9090/metrics. - Structured JSON logging — all requests and errors logged with Winston.
- Audit trail — every authenticated action logged with client identity, tool name, and parameters.
- Grafana dashboard — pre-built dashboard JSON included in the repo.
- Health & readiness endpoints —
/healthand/readyfor uptime monitoring and Kubernetes probes.
dryRun Safety Mode
Every mutating tool accepts a dryRun: true parameter. When set, the tool logs exactly what it would do and returns a [dryRun]-prefixed description — without touching your WHMCS data.
Use it when testing new AI prompts, or set it as the default in your system prompt to give an AI read-write tool access with a human-approval step before anything actually changes.
Deployment
Three supported deployment methods:
- Docker Compose — recommended for production. Handles updates, persistent storage, and reverse proxy (Traefik/nginx) integration.
- Kubernetes — manifest with PVC, secrets, ingress, and ServiceMonitor included in the repo.
- Standalone binary — for servers without Docker. Managed via systemd.
Support
- Support tickets: daddar.io/contact
- GitHub issues & discussions: github.com/daddariotech/whmcs-mcp
- Changelog: daddar.io/whmcs-mcp/changelog
