WHMCS MCP Server

The first production-grade AI integration for WHMCS. Connect ChatGPT, Claude, and Cursor directly to your WHMCS installation — manage clients, invoices, tickets, and services through natural language.

You: "Send a payment reminder to all clients with overdue invoices over $50"
AI:  Fetching overdue invoices... Found 12. Sending reminder emails... Done.

---

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 you trust the AI:

Minimum permissions (read-only — AI can look but not touch): GetClients GetClientsDetails GetClientsProducts GetClientsDomains GetClientsAddons GetClientGroups GetContacts GetEmails GetInvoice GetInvoices GetOrders GetOrderStatuses GetProducts GetTicket GetTickets GetSupportDepartments GetQuotes GetCredits GetTransactions GetStats GetActivityLog GetCancelledPackages GetEmailTemplates GetCurrencies GetPaymentMethods GetHealthStatus GetProductGroups GetRegistrars GetServers GetAffiliates GetAnnouncements GetSupportStatuses GetTicketCounts GetTicketPredefinedCats GetAdminUsers GetToDoItems GetToDoItemStatuses GetStaffOnline DomainWhois DomainGetNameservers DomainGetLockingStatus GetTLDPricing GetPromotions GetProjects GetProject

Maximum permissions (full access — AI can take any action): Everything above, plus: AddClient UpdateClient AddClientNote AddContact UpdateContact CreateInvoice AddInvoicePayment AddOrder AcceptOrder CancelOrder OpenTicket AddTicketReply UpdateTicket CreateQuote UpdateQuote SendQuote AcceptQuote DeleteQuote AddCredit ApplyCredit AddBillableItem SendEmail UpdateClientProduct ModuleSuspend ModuleUnsuspend ModuleTerminate ModuleCreate UpgradeProduct DomainRegister DomainTransfer DomainRenew DomainUpdateNameservers DomainUpdateLockingStatus DomainToggleIdProtect FraudOrder PendingOrder UpdateInvoice ModuleChangePw LogActivity AddTicketNote AffiliateActivate CreateProject UpdateProject AddProjectTask UpdateProjectTask DeleteProjectTask AddProjectMessage StartTaskTimer EndTaskTimer

Project Management tools: list_projects through end_task_timer additionally require the WHMCS Project Management addon to be active (Setup → Addon Modules), regardless of API role permissions.

Domain write permissions: register_domain, transfer_domain, and renew_domain require DomainRegister, DomainTransfer, and DomainRenew respectively. Note the Domain prefix comes first — RegisterDomain / TransferDomain / RenewDomain are not valid WHMCS permission keys and are silently ignored if granted. If a domain tool returns HTTP 403, the matching permission is missing from your role. Upgrading from 2.3.1 or earlier? See the 2.3.2 changelog entry — you need to re-grant these three under their correct names.

Tip: Start with minimum permissions and add write permissions only as needed. This limits blast radius if an AI client goes rogue or gets a bad prompt.

2. Set an API Access Key (recommended)

An Access Key bypasses IP restrictions entirely — the recommended approach since the MCP server's outbound IP can change (Docker restarts, server moves, etc.).

Add this line to your configuration.php in the WHMCS root:

$api_access_key = 'your-secret-passphrase';

Allowed characters: letters, numbers, and ! @ # $ % . ( ) * [ ] - _

Then set WHMCS_ACCESS_KEY to the same value in your .env or Portainer stack.

3. Create an API Credential

Setup → Staff Management → API Credentials → Generate New Credential

• Role: select the role you just created
• Allowed IPs: leave blank if using an Access Key (recommended), or enter the server IP if you prefer IP-based restrictions
• Copy the Identifier and Secret — you'll need these during install

---

Quick Start — running in under 5 minutes

Binary (no Docker required):

curl -fsSL https://daddar.io/whmcs-mcp/install.sh | sudo bash

Prompts for your WHMCS credentials and license key, installs the binary to /usr/local/bin, and registers a systemd service.

Docker (recommended for servers already running Docker):

curl -fsSL https://daddar.io/whmcs-mcp/install-docker.sh | bash

Prompts for credentials, writes .env, and starts the stack via Docker Compose.

---

Get a License

Purchase a license at daddar.io/store/ai-tools/whmcs-mcp — after checkout, your license key appears in the client portal. Paste it into setup.sh when prompted.

No license? A 14-day free trial starts automatically on first run.

---

What You Can Do

96 WHMCS Tools

All tools support dryRun mode — preview what would happen before making changes.

24 Real-Time Resources

Resources are read-only data endpoints that AI clients can subscribe to via whmcs:// URIs. Data is served from a 60-second TTL cache.

18 Workflow Prompts

Prompts are pre-built workflow templates that MCP clients surface as one-click guided interactions.

vs other WHMCS MCP servers

---

Supported AI Clients

---

Security

• OAuth 2.0 PKCE — industry-standard authorization with short-lived tokens and refresh
• Bearer token mode — simple API key setup for single-tenant deployments
• Rate limiting — per-IP and per-token controls (configurable)
• Audit log — every authenticated request logged with client ID, method, and timestamp
• Helmet.js — security headers (CSP, HSTS, X-Frame-Options, etc.)
• Input sanitization — defense-in-depth against injection
• HTTPS enforcement — rejects plain HTTP in production
• Docker secrets — credentials read from /run/secrets/ if present

---

Configuration

Environment Variables

Copy .env.example to .env and fill in your values.

Required:

License:

Authentication:

Note (v2.1.0): MCP_AUTH_MODE and MCP_REQUIRE_AUTH have been removed. The server always runs the full auth stack — bearer tokens and OAuth are both available in every configuration. Auth is always enforced in HTTP mode.

Network / proxy:

Observability (optional):

Webhooks (optional):

See .env.example for all options.

---

Connecting AI Clients

Cursor IDE

Bearer token (simple): Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

OAuth (New App UI): When adding via Cursor's "New App" with OAuth, the server must have MCP_CLIENT_REGISTRATION_SECRET set (in Portainer or .env). Generate with openssl rand -hex 24, set it on the server, then enter the same value in Cursor's Advanced OAuth settings under "Client registration secret" (or equivalent). This enables Dynamic Client Registration so Cursor can self-register.

Or for local stdio mode:

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["/path/to/whmcs-mcp/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.example.com",
        "WHMCS_IDENTIFIER": "your-identifier",
        "WHMCS_SECRET": "your-secret"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

ChatGPT (GPT Actions)

Point your GPT Action schema at https://your-server:3100/mcp. Use OAuth 2.0 mode for multi-user setups.

---

Real-Time Webhook Push

Receive WHMCS events pushed to your AI in real time — new tickets, invoices, overdue payments.

See docs/WEBHOOKS.md for setup instructions.

---

Deployment

Docker Compose (recommended)

docker compose -f docker-compose.marketplace.yml up -d

Generates tokens:

docker exec -it whmcs-mcp node dist/scripts/auth-cli.js generate \
  --name "My AI" --scopes "mcp:read,mcp:write"

Kubernetes

See k8s-deployment.yaml and DEPLOYMENT.md.

Behind a Reverse Proxy (nginx / Caddy / Traefik)

Remove the ports block from docker-compose.marketplace.yml and proxy to whmcs-mcp:3100. See comments in that file.

---

Observability

• Health check: GET /health
• Readiness: GET /ready
• Prometheus metrics: port 9090 (configurable via MCP_METRICS_PORT)

Key metrics: whmcs_mcp_requests_total, whmcs_mcp_request_duration_seconds, whmcs_mcp_active_sessions, whmcs_mcp_auth_total

---

Support & Licensing

• Purchase / manage license: daddar.io/store/ai-tools/whmcs-mcp
• Documentation: this repo + DEPLOYMENT.md + docs/WEBHOOKS.md
• Support: support@daddar.io
• Security issues: SECURITY.md

Copyright © 2026 Daddario Tech Solutions. All rights reserved. See LICENSE.