Installation Guide

MCP Server for WHMCS

Connect Claude Desktop to WHMCS in 15 minutes

For beginners · No coding required · Step-by-step guide

Last updated: January 2026

View product details & pricing

Before You Start

Estimated time: 15-20 minutes

Level: Beginner · No technical knowledge required

Important: Use Claude Desktop, NOT claude.ai

This guide is for the Claude Desktop app (installed on your computer), NOT the web version at claude.ai. MCP servers only work with Claude Desktop.

If you don't have Claude Desktop installed, download it here first →

What you'll need:

WHMCS installed and running
Admin access to WHMCS
Claude Desktop installedDownload →
MCP Server addon files (mx_mcp.zip)
License Key (received via email after purchase)

Note: Claude Desktop is free to use. No paid account required for this integration.

Part 1: Install Addon in WHMCS

Step 1.1: Upload Files

1.Open your FTP client (FileZilla, Cyberduck, etc.)
2.Connect to your WHMCS server
3.Navigate to: /public_html/whmcs/modules/addons/
4.Extract mx_mcp.zip on your computer
5.Upload the entire mx_mcp/ folder

Expected folder structure:

/whmcs/modules/addons/mx_mcp/
├── mx_mcp.php
├── api.php
├── hooks.php
├── .htaccess
└── lib/
    ├── Admin/
    ├── Api/
    └── Database.php

Step 1.2: Activate Addon

1.Open your browser and go to your WHMCS admin: http://your-whmcs.com/admin
2.Login with your administrator account
3.Go to: Setup → Addon Modules
4.Find "MCP Server" in the list
5.Click "Activate"
6.
Configure settings:
- • License Key: Paste your license key (received via email)
- • Enable API: ON
- • Log API Requests: ON
- • Rate Limit: 100
- • Access Control: Full Administrator
7.Click "Save Changes"
8.Verify License Status shows "Active"

Important: License Required

The MCP Server requires an active license to function. Without a valid license, the API will return a license error and Claude will not be able to connect to your WHMCS.

Success check: You should see "Changes Saved Successfully" and License Status should display "Active"

Step 1.3: Generate API Key

1.Go to: Addons → MCP Server
2.Click on "API Keys" tab or "Generate New API Key" button
3.Enter a descriptive Key Name (e.g., "Claude Desktop")
4.Click "Generate"

Important: Copy the API Secret immediately

After clicking "Generate", you'll see a popup showing the API Secret. This is shown only once and cannot be retrieved later.

You need both values:

• API Key - visible in the table (64 characters)
• API Secret - shown only once in popup (copy immediately)

If you lose the secret, you'll need to generate a new API key.

Part 2: Configure Claude Desktop

Choose your installation method:

One-Click Install (Recommended)

macOS and Windows only. The easiest way to install.

1.Download the .mcpb file from your purchase email or client area
2.Double-click the file
3.Claude Desktop opens automatically with a configuration screen
4.Enter your WHMCS API URL, API Key, and API Secret
5.Click "Install" - Done!

No terminal, no config files, no technical knowledge required.

Manual Install (All Platforms)

For Linux users or if the one-click install doesn't work.

Step 1: Find Config File

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Step 2: Download and Extract

1. Download mx-mcp-server-1.0.0.zip from your client area
2. Extract to a permanent location:

macOS:

~/Library/Application Support/mx-mcp-server/

Windows:

%LOCALAPPDATA%\mx-mcp-server\

Or simply: C:\mx-mcp-server\

Linux:

~/.local/share/mx-mcp-server/

Or simply: /opt/mx-mcp-server/

Choose whichever location you prefer. Just remember the path for the next step.

Step 3: Install Dependencies

Open a terminal and navigate to the extracted folder, then run:

npm install

macOS / Linux:

cd ~/Library/Application\ Support/mx-mcp-server && npm install

Windows (PowerShell):

cd $env:LOCALAPPDATA\mx-mcp-server; npm install

This installs the required dependencies. You only need to do this once after extracting.

Step 4: Edit Config File

Copy this configuration (choose your OS):

macOS / Linux:

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["$HOME/Library/Application Support/mx-mcp-server/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.com/modules/addons/mx_mcp/api.php",
        "WHMCS_API_KEY": "YOUR_API_KEY",
        "WHMCS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["C:\Users\YourName\AppData\Local\mx-mcp-server\dist\index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.com/modules/addons/mx_mcp/api.php",
        "WHMCS_API_KEY": "YOUR_API_KEY",
        "WHMCS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

Replace YourName with your Windows username. Use double backslashes (\\) in JSON.

Replace these values:

your-whmcs.com → Your WHMCS domain
YOUR_API_KEY → Your 64-character API key
YOUR_API_SECRET → Your API secret

Step 5: Restart Claude Desktop

Close completely (Cmd+Q on Mac, Alt+F4 on Windows) and reopen.

Other AI Clients (Cursor, Windsurf, etc.)

MCP Server works with any MCP-compatible client. Download and extract the ZIP first (see Step 2 above for recommended locations).

Cursor

Config file location:

Global: ~/.cursor/mcp.json
Per project: .cursor/mcp.json in your project folder

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["/Users/yourname/Library/Application Support/mx-mcp-server/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.com/modules/addons/mx_mcp/api.php",
        "WHMCS_API_KEY": "YOUR_API_KEY",
        "WHMCS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

Replace /Users/yourname/ with your actual home path. Use echo $HOME in terminal to find it.

Windsurf

Config file:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["/Users/yourname/Library/Application Support/mx-mcp-server/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.com/modules/addons/mx_mcp/api.php",
        "WHMCS_API_KEY": "YOUR_API_KEY",
        "WHMCS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

Cline (VS Code Extension)

Config file:

.vscode/mcp.json

Or open VS Code settings and search for "Cline MCP":

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["/Users/yourname/Library/Application Support/mx-mcp-server/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.com/modules/addons/mx_mcp/api.php",
        "WHMCS_API_KEY": "YOUR_API_KEY",
        "WHMCS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

Other MCP Clients

Any client that supports MCP can use this server. The configuration is similar - you need the path to dist/index.js and your API credentials. Check your client's documentation for the config file location.

Requirement: Node.js 18+

For manual installation, you need Node.js 18 or higher installed. Download Node.js →

Part 3: Test the Connection

Test 1: Verify Connection

Open Claude Desktop and look for connection indicator.

Success: You should see "MCP Servers: 1 connected" or a tools icon.

Test 2: First Query

Type this in Claude:

Using the WHMCS MCP server, get the system status.

You should see system info like WHMCS version, PHP version, and client count.

Test 3: List Clients

Type this:

Show me a list of all clients in WHMCS.

If you see a list of clients with names and emails, it works!

Troubleshooting

Claude doesn't show MCP Servers connected

•Check config file is saved correctly
•Verify npx is installed: run npx --version in terminal
•Check Claude logs at ~/Library/Logs/Claude/
•Restart Claude Desktop

Claude says I don't have access to WHMCS

•Verify WHMCS URL is correct
•Check API key and secret are copied correctly
•Test API manually with curl command
•Check addon is activated in WHMCS

Error: "Module license is invalid or expired"

•Go to WHMCS Admin → Setup → Addon Modules → MCP Server → Configure
•Enter your License Key in the License Key field
•Click "Save Changes"
•Verify License Status shows "Active"
•If license is correct but still invalid, contact support

Error: "API key is not active"

•Go to WHMCS Admin → Addons → MCP Server
•Check API Keys tab
•Verify key shows is_active = 1
•Click "Activate" if needed

Contact Support Review Checklist

Tools Reference

MCP Server includes 28 tools organized into 6 categories. Each tool can be invoked through natural language.

Client Management

4 tools

Service Lifecycle

6 tools

Order Management

5 tools

Invoice Management

5 tools

Quote Management

4 tools

Support Tickets

4 tools

Tip: You don't need to remember tool names. Simply describe what you want in natural language and Claude will use the appropriate tool automatically.

View Full Tools Reference

Congratulations!

You've successfully connected Claude to your WHMCS. Try these example prompts:

"Show me today's revenue"

"List all pending orders"

"Which clients opened tickets this week?"

"Update client #7's phone number"

View all 28 tools above →