whmcs-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# WHMCS MCP Server
+
+[![CI](https://github.com/not-sure-w/whmcs-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/not-sure-w/whmcs-mcp-server/actions/workflows/ci.yml)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
+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
+
+```bash
+npm install -g whmcs-mcp-server
+```
+
+Or clone the repo:
+
+```bash
+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:
+
+```bash
+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](#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](#security-configuration) section below.
+
+## Integration
+
+### OpenCode
+
+Add to your `opencode.json`:
+
+```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`:
+
+```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:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP configuration:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+### Generic Stdio (any MCP client)
+
+```json
+{
+  "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
+
+```bash
+docker compose up
+```
+
+Development with hot-reload:
+
+```bash
+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
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run `npm run validate` to ensure all checks pass
+4. Commit and push
+5. Open a Pull Request
+
+## License
+
+ISC License — see [LICENSE](LICENSE) for details.
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/not-sure-w/whmcs-mcp-server/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/not-sure-w/whmcs-mcp-server/discussions)
+- **Support development:** [Buy me a coffee](https://buymeacoffee.com/whmcsmcp)
+
+### Consulting & Custom Development
+
+Need help integrating WHMCS with AI agents or want custom MCP tools built for your setup?
+
+- **Email:** hello@whmcsmcp.com
+- **GitHub:** [Contact via Issues](https://github.com/not-sure-w/whmcs-mcp-server/issues)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }