Model Context Protocol (MCP) Server for WHMCS
================================================================================

Connect AI assistants directly into your WHMCS workflow. Ask questions in plain
English and get instant answers from your client data, invoices, tickets, and
more. No external APIs. Your data stays on your server.

Supported Clients:
- Claude Desktop (Recommended)
- Cursor, Cline, Zed developer tools
- ChatGPT (via MCP bridge)
- Ollama (for 100% private local LLMs)

--------------------------------------------------------------------------------
INSTALLATION
--------------------------------------------------------------------------------

1. Upload the `whmcs_mcp` directory to your WHMCS installation under:
   `/modules/addons/`

   The final path should be:
   `/modules/addons/whmcs_mcp/whmcs_mcp.php`

2. Log in to your WHMCS Admin Area.

3. Navigate to:
   - WHMCS v7/v8: Setup -> Addon Modules
   - WHMCS v8.1+: System Settings -> Addon Modules

4. Find "Model Context Protocol (MCP) Server" in the list and click "Activate".

5. Click "Configure" next to the module:
   - Check the Admin Role Groups that are allowed to access the dashboard.
   - Enter a License Key (any value is accepted).
   - Choose whether to delete database tables on deactivation.
   - Click "Save Changes".

6. Access the dashboard via:
   Addons -> Model Context Protocol (MCP) Server

--------------------------------------------------------------------------------
CONNECTION METHODS (CLAUDE DESKTOP STEP-BY-STEP)
--------------------------------------------------------------------------------

Option 1: Stdio Transport (Local CLI)
-------------------------------------
Use this option if Claude Desktop is running on the same server as your WHMCS
installation, or if you are connecting via a local developer environment.

Step-by-step configuration:
1. Open your Claude Desktop configuration file:
   - Easy Way (Recommended): Open the Claude Desktop app, go to Settings,
     select the Developer tab, and click "Open Config".
   - Manual Way (Windows): Press Win+R, type "%appdata%\Claude\" and press Enter. 
     Open "claude_desktop_config.json".
   - Manual Way (macOS): Press Cmd+Shift+G, type "~/Library/Application Support/Claude/"
     and press Enter. Open "claude_desktop_config.json".
2. If the file does not exist, create a new text file named "claude_desktop_config.json".
3. Copy and paste the configuration block below into the file:

{
  "mcpServers": {
    "whmcs-mcp-local": {
      "command": "php",
      "args": [
        "D:/work/whmcs/my-modules/WHMCS MCP/mcp.php"
      ]
    }
  }
}

4. Save the file and completely restart Claude Desktop (exit from the system tray
   and reopen).
5. Click the plug icon in the bottom-right of the Claude chat window to verify
   the tools are loaded.


Option 2: Claude.ai Web Connector (Synced)
------------------------------------------
Use this option to connect your Claude.ai Web Account. Once added, the connection
and all tools will automatically sync and be available in both your web browser
and your Claude Desktop app (no local file editing required!).

*FIREWALL WHITELIST REQUIRED*
Please ask your server administrator to whitelist Anthropic's official IP ranges
in your server firewall (e.g. CSF/WHM or Hetzner):
- IPv4 Range: 160.79.104.0/23
- IPv6 Range: 2607:6bc0::/48

Step-by-step configuration:
1. Log in to your WHMCS Admin Area.
2. Go to Addons -> Model Context Protocol (MCP) Server.
3. Under the "API Keys" tab, generate a new API key.
4. Log in to your Claude.ai account in your web browser.
5. Click on your profile icon (or team settings) and select "Connectors" (or "Custom Connectors").
6. Click "Add custom connector" and fill out the form:
   - Name: WHMCS MCP
   - Remote MCP server URL: 
     https://whmcs.whmpress.com/modules/addons/whmcs_mcp/api.php?action=sse&api_key=YOUR_API_KEY
   - Advanced Settings (OAuth): Leave empty.
   - Individual sign-in: Keep toggled ON.
7. Replace "YOUR_API_KEY" in the URL above with the actual API Key you generated in Step 3.
8. Click "Add". Claude will connect and show your 84 WHMCS tools in your web and desktop chat!


--------------------------------------------------------------------------------
SECURITY & PRIVACY
--------------------------------------------------------------------------------

- Hashed API Keys: API keys are hashed using SHA-256 in the database.
- Granular Permissions: You can restrict each API key to specific tools.
- Rate Limiting: Built-in request rate limiting protects your WHMCS from abuse.
- Audit Logging: Every tool execution is logged with the client's IP and status.
- HTTPS Enforced: By default, HTTPS is required for all remote SSE connections.
