{
  "markdown": "# WHMCS MCP Server\n\n**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.\n\n```\nYou: \"Send a payment reminder to all clients with overdue invoices over $50\"\nAI:  Fetching overdue invoices... Found 12. Sending reminder emails... Done.\n```\n\n[![License](https://img.shields.io/badge/license-Commercial-blue)](https://daddar.io)\n[![Docker](https://img.shields.io/docker/v/daddariotech/whmcs-mcp?label=docker)](https://hub.docker.com/r/daddariotech/whmcs-mcp)\n[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)\n\n---\n\n## Prerequisites — WHMCS API Setup\n\nBefore running the installer you need a WHMCS API credential with the right permissions.\n\n**1. Create an API Role**\n\nIn WHMCS Admin: **Setup → Staff Management → API Roles → Add Role**\n\nChoose a permission preset based on how much you trust the AI:\n\n**Minimum permissions (read-only — AI can look but not touch):**\n`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`\n\n**Maximum permissions (full access — AI can take any action):**\nEverything above, plus:\n`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`\n\n> **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.\n\n> **Domain write permissions:** `register_domain`, `transfer_domain`, and `renew_domain` require\n> `DomainRegister`, `DomainTransfer`, and `DomainRenew` respectively. Note the `Domain` prefix\n> comes first — `RegisterDomain` / `TransferDomain` / `RenewDomain` are not valid WHMCS permission\n> keys and are silently ignored if granted. If a domain tool returns HTTP 403, the matching\n> permission is missing from your role. Upgrading from 2.3.1 or earlier? See the\n> [2.3.2 changelog entry](CHANGELOG.md) — you need to re-grant these three under their correct\n> names.\n\n> **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.\n\n**2. Set an API Access Key (recommended)**\n\nAn Access Key bypasses IP restrictions entirely — the recommended approach since the MCP server's outbound IP can change (Docker restarts, server moves, etc.).\n\nAdd this line to your `configuration.php` in the WHMCS root:\n\n```php\n$api_access_key = 'your-secret-passphrase';\n```\n\n> Allowed characters: letters, numbers, and `! @ # $ % . ( ) * [ ] - _`\n\nThen set `WHMCS_ACCESS_KEY` to the same value in your `.env` or Portainer stack.\n\n**3. Create an API Credential**\n\n**Setup → Staff Management → API Credentials → Generate New Credential**\n\n- Role: select the role you just created\n- Allowed IPs: leave blank if using an Access Key (recommended), or enter the server IP if you prefer IP-based restrictions\n- Copy the **Identifier** and **Secret** — you'll need these during install\n\n---\n\n## Quick Start — running in under 5 minutes\n\n**Binary (no Docker required):**\n\n```bash\ncurl -fsSL https://daddar.io/whmcs-mcp/install.sh | sudo bash\n```\n\nPrompts for your WHMCS credentials and license key, installs the binary to `/usr/local/bin`, and registers a systemd service.\n\n**Docker (recommended for servers already running Docker):**\n\n```bash\ncurl -fsSL https://daddar.io/whmcs-mcp/install-docker.sh | bash\n```\n\nPrompts for credentials, writes `.env`, and starts the stack via Docker Compose.\n\n---\n\n## Get a License\n\nPurchase a license at **[daddar.io/store/ai-tools/whmcs-mcp](https://daddar.io/store/ai-tools/whmcs-mcp)** — after checkout, your license key appears in the client portal. Paste it into `setup.sh` when prompted.\n\nNo license? A **14-day free trial** starts automatically on first run.\n\n---\n\n## What You Can Do\n\n### 96 WHMCS Tools\n\n| Category | Tools |\n|---|---|\n| **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` |\n| **Invoices** | `get_invoice` `list_invoices` `create_invoice` `add_invoice_payment` `get_overdue_invoices` `get_transactions` `update_invoice` |\n| **Orders** | `add_order` `get_orders` `accept_order` `cancel_order` `get_order_statuses` `fraud_order` `pending_order` |\n| **Services** | `list_services` `update_service` `upgrade_product` `module_create` `module_suspend` `module_unsuspend` `module_terminate` `get_cancelled_packages` |\n| **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` |\n| **Quotes** | `get_quotes` `create_quote` `send_quote` `accept_quote` `update_quote` `delete_quote` |\n| **Contacts** | `get_contacts` `add_contact` `update_contact` |\n| **Credits** | `get_credits` `add_credit` `apply_credit` |\n| **Billing** | `add_billable_item` `get_payment_methods` `get_currencies` |\n| **Email** | `send_email` `get_email_templates` |\n| **Products** | `get_products` `get_product_groups` |\n| **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` |\n| **Admin** | `get_admin_users` `get_staff_online` `get_whmcs_details` `log_activity` `get_activity_log` |\n| **Affiliates** | `get_affiliates` `activate_affiliate` |\n| **Promotions** | `get_promotions` |\n| **Servers** | `get_servers` `module_change_password` |\n| **System** | `get_health_status` `get_todo_items` `get_todo_item_statuses` `get_announcements` `get_registrars` `get_stats` |\n| **Reports** | `get_stats` `get_activity_log` `get_transactions` |\n| **Projects** | `list_projects` `get_project` `create_project` `update_project` `add_project_task` `update_project_task` `delete_project_task` `add_project_message` `start_task_timer` `end_task_timer` — requires the WHMCS **Project Management addon** to be active |\n\nAll tools support `dryRun` mode — preview what would happen before making changes.\n\n### 24 Real-Time Resources\n\nResources are read-only data endpoints that AI clients can subscribe to via `whmcs://` URIs. Data is served from a 60-second TTL cache.\n\n| URI | Description |\n|---|---|\n| `whmcs://stats` | Live system statistics (revenue, client counts, invoice totals) |\n| `whmcs://health` | Server health status |\n| `whmcs://system/info` | WHMCS installation details (version, PHP, database) |\n| `whmcs://products` | Full product and service catalog |\n| `whmcs://product-groups` | Product groups with product counts |\n| `whmcs://tld-pricing` | Domain TLD registration/transfer/renewal pricing |\n| `whmcs://promotions` | Active promotions and coupon codes |\n| `whmcs://order-statuses` | Available order status values |\n| `whmcs://currencies` | Configured currencies with exchange rates |\n| `whmcs://payment-methods` | Active payment gateway modules |\n| `whmcs://registrars` | Configured domain registrar modules |\n| `whmcs://servers` | Provisioning servers |\n| `whmcs://client-groups` | Client group definitions |\n| `whmcs://affiliates` | Registered affiliate accounts |\n| `whmcs://email-templates` | Email template library |\n| `whmcs://announcements` | Published announcements |\n| `whmcs://support/departments` | Support departments |\n| `whmcs://support/statuses` | Available ticket status values |\n| `whmcs://support/ticket-counts` | Ticket counts by department and status |\n| `whmcs://support/predefined-categories` | Predefined ticket reply categories |\n| `whmcs://admin/users` | Admin user accounts |\n| `whmcs://admin/todo` | Admin to-do items |\n| `whmcs://admin/todo-statuses` | Available to-do item status values |\n| `whmcs://admin/staff-online` | Staff currently logged into the admin area |\n\n### 18 Workflow Prompts\n\nPrompts are pre-built workflow templates that MCP clients surface as one-click guided interactions.\n\n| Prompt | Description |\n|---|---|\n| `new_client` | Guided new client account creation |\n| `new_order` | Place and accept a product order for a client |\n| `new_invoice` | Create a custom invoice with optional send |\n| `new_quote` | Draft a sales quote with send/accept lifecycle |\n| `ticket_response` | Load a ticket, draft a professional staff reply |\n| `client_onboarding` | Full account onboarding review checklist |\n| `fraud_investigation` | Security audit for a suspicious order |\n| `bulk_invoice_reminder` | Find overdue invoices and send payment reminders |\n| `revenue_report` | MRR + outstanding + paid financial breakdown |\n| `client_health_check` | Deep account scorecard (services, billing, support) |\n| `domain_expiry_audit` | Flag at-risk domains, draft renewal reminders |\n| `new_product_setup` | Step-by-step product configuration guide |\n| `churn_risk_report` | Ranked churn-risk table with recommended actions |\n| `support_queue_triage` | Priority-ordered ticket queue with quick-win suggestions |\n| `affiliate_performance` | Top performers, commissions, activation gaps |\n| `service_renewal_forecast` | N-month renewal revenue projection |\n| `addon_upsell_opportunities` | Missing add-on detection + upsell quote generation |\n| `promo_effectiveness` | Promo code usage, revenue impact, and expiry analysis |\n\n### vs other WHMCS MCP servers\n\n| Feature | WHMCS MCP Server (us) | scarecr0w12/whmcs-mcp-tool | MX Modules |\n|---|---|---|---|\n| Tools | 86 | ~50 | ~20 |\n| HTTP transport (ChatGPT, Claude remote) | Yes | **No — stdio only** | Yes |\n| Authentication | OAuth 2.0 PKCE + bearer tokens | **None** | Static tokens only |\n| One-click install | Yes (`curl \\| bash`) | Manual (clone + npm) | Manual |\n| Real-time webhook push | Yes | No | No |\n| Audit log | Yes | No | No |\n| Prometheus metrics | Yes | No | No |\n| Rate limiting | Yes | No | No |\n| `dryRun` mode on every tool | Yes | No | No |\n| Trial period | 14 days free | Free forever (MIT) | None |\n| Commercial support | Yes | None | Limited |\n| License | Commercial | MIT | Commercial |\n\n---\n\n## Supported AI Clients\n\n| Client | Transport | Auth |\n|---|---|---|\n| **ChatGPT** (via GPT Actions) | HTTP | Bearer token or OAuth 2.0 |\n| **Claude Desktop** | HTTP | Bearer token or OAuth 2.0 |\n| **Cursor IDE** | stdio or HTTP | Bearer token or OAuth 2.0 |\n| **Any MCP-compatible client** | HTTP | Bearer token or OAuth 2.0 |\n\n---\n\n## Security\n\n- **OAuth 2.0 PKCE** — industry-standard authorization with short-lived tokens and refresh\n- **Bearer token mode** — simple API key setup for single-tenant deployments\n- **Rate limiting** — per-IP and per-token controls (configurable)\n- **Audit log** — every authenticated request logged with client ID, method, and timestamp\n- **Helmet.js** — security headers (CSP, HSTS, X-Frame-Options, etc.)\n- **Input sanitization** — defense-in-depth against injection\n- **HTTPS enforcement** — rejects plain HTTP in production\n- **Docker secrets** — credentials read from `/run/secrets/` if present\n\n---\n\n## Configuration\n\n### Environment Variables\n\nCopy `.env.example` to `.env` and fill in your values.\n\n**Required:**\n\n| Variable | Description |\n|---|---|\n| `WHMCS_API_URL` | Your WHMCS URL, e.g. `https://billing.example.com` |\n| `WHMCS_IDENTIFIER` | WHMCS API identifier |\n| `WHMCS_SECRET` | WHMCS API secret |\n\n**License:**\n\n| Variable | Description | Default |\n|---|---|---|\n| `LICENSE_KEY` | Your license key from daddar.io | (14-day free trial starts automatically) |\n\n**Authentication:**\n\n| Variable | Description | Default |\n|---|---|---|\n| `MCP_OAUTH_ADMIN_PASSWORD` | Enables the `/authorize` consent UI for OAuth PKCE flows | (unset — consent UI disabled) |\n| `MCP_OAUTH_SESSION_SECRET` | Secret used to sign OAuth CSRF session cookies. Generate with `openssl rand -hex 32`. | (auto-generated ephemeral — set this in production) |\n| `MCP_AUTH_TOKENS_FILE` | Path to bearer token store | `/app/data/tokens.json` |\n\n> **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.\n\n**Network / proxy:**\n\n| Variable | Description | Default |\n|---|---|---|\n| `MCP_TRUST_PROXY` | Set to `true` when the server runs behind a TLS-terminating reverse proxy (Traefik, nginx, etc.). Enables `X-Forwarded-*` header trust for correct IP detection and HTTPS enforcement. | `false` *(changed in v2.2.0 — set explicitly in production)* |\n\n**Observability (optional):**\n\n| Variable | Description | Default |\n|---|---|---|\n| `MCP_METRICS_ENABLED` | Enable Prometheus metrics endpoint | `true` |\n| `MCP_METRICS_PORT` | Port for `/metrics` endpoint | `9090` |\n| `PUSHGATEWAY_URL` | Prometheus Pushgateway URL for metric push | (unset) |\n| `PUSHGATEWAY_USER` | HTTP Basic Auth username for Pushgateway | (unset) |\n| `PUSHGATEWAY_PASSWORD` | HTTP Basic Auth password for Pushgateway | (unset) |\n\n**Webhooks (optional):**\n\n| Variable | Description |\n|---|---|\n| `WHMCS_WEBHOOK_SECRET` | HMAC secret shared with your WHMCS PHP hook |\n\nSee [.env.example](.env.example) for all options.\n\n---\n\n## Connecting AI Clients\n\n### Cursor IDE\n\n**Bearer token (simple):** Add to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"whmcs\": {\n      \"url\": \"https://your-server:3100/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**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.\n\nOr for local stdio mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"whmcs\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/whmcs-mcp/dist/index.js\"],\n      \"env\": {\n        \"WHMCS_API_URL\": \"https://your-whmcs.example.com\",\n        \"WHMCS_IDENTIFIER\": \"your-identifier\",\n        \"WHMCS_SECRET\": \"your-secret\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"whmcs\": {\n      \"url\": \"https://your-server:3100/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n### ChatGPT (GPT Actions)\n\nPoint your GPT Action schema at `https://your-server:3100/mcp`. Use OAuth 2.0 mode for multi-user setups.\n\n---\n\n## Real-Time Webhook Push\n\nReceive WHMCS events pushed to your AI in real time — new tickets, invoices, overdue payments.\n\nSee [docs/WEBHOOKS.md](docs/WEBHOOKS.md) for setup instructions.\n\n---\n\n## Deployment\n\n### Docker Compose (recommended)\n\n```bash\ndocker compose -f docker-compose.marketplace.yml up -d\n```\n\nGenerates tokens:\n\n```bash\ndocker exec -it whmcs-mcp node dist/scripts/auth-cli.js generate \\\n  --name \"My AI\" --scopes \"mcp:read,mcp:write\"\n```\n\n### Kubernetes\n\nSee [k8s-deployment.yaml](k8s-deployment.yaml) and [DEPLOYMENT.md](DEPLOYMENT.md).\n\n### Behind a Reverse Proxy (nginx / Caddy / Traefik)\n\nRemove the `ports` block from `docker-compose.marketplace.yml` and proxy to `whmcs-mcp:3100`. See comments in that file.\n\n---\n\n## Observability\n\n- **Health check:** `GET /health`\n- **Readiness:** `GET /ready`\n- **Prometheus metrics:** port 9090 (configurable via `MCP_METRICS_PORT`)\n\nKey metrics: `whmcs_mcp_requests_total`, `whmcs_mcp_request_duration_seconds`, `whmcs_mcp_active_sessions`, `whmcs_mcp_auth_total`\n\n---\n\n## Support & Licensing\n\n- **Purchase / manage license:** [daddar.io/store/ai-tools/whmcs-mcp](https://daddar.io/store/ai-tools/whmcs-mcp)\n- **Documentation:** this repo + [DEPLOYMENT.md](DEPLOYMENT.md) + [docs/WEBHOOKS.md](docs/WEBHOOKS.md)\n- **Support:** [support@daddar.io](mailto:support@daddar.io)\n- **Security issues:** [SECURITY.md](SECURITY.md)\n\nCopyright © 2026 Daddario Tech Solutions. All rights reserved. See [LICENSE](LICENSE).\n",
  "bytes": 17592,
  "sha": "1fe1724a37f64160061f96c05de71392f0741a5c5e86e2b008441987d5ad623f",
  "repo_slug": "daddariotech/whmcs-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_daddariotech_whmcs_mcp_9df90160/readme"
}