Installation Guide

MCP Server for WHMCS

Connect Claude Desktop to WHMCS in 2-3 minutes

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

Last updated: March 2026 · v1.3.0

View product details & pricing

Before You Start

Estimated time: 2-3 minutes

Level: Beginner · No technical knowledge required

What changed in v1.3.0

Aspect	Before v1.3.0	From v1.3.0
Server	Separate Node.js process	PHP addon (built-in)
Authentication	API Key + Secret	Bearer token
Setup time	10-15 minutes	2-3 minutes
Node.js	Required for server	Not required by addon
Config	Manual JSON editing	Setup Assistant (copy and paste)

Note: Node.js is not required by the addon

The addon does not require Node.js. If you use Claude Desktop, Node.js must be installed on your machine because Claude Desktop uses npx to run mcp-remote as a connection bridge. This is a Claude Desktop limitation, not an addon requirement. Cursor, VS Code, and Windsurf connect directly without Node.js.

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.) or cPanel File Manager
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
├── mcp.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: Configuration → 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 Bearer Token

1.Go to: Addons → MCP Server
2.Click the API Keys tab
3.Click Generate New Credential
4.Enter a descriptive name (e.g., "Claude Desktop" or "Cursor")
5.Click "Generate"

Important: Copy the Bearer token immediately

After clicking "Generate", your Bearer token is displayed only once and cannot be retrieved later. Copy it somewhere safe before closing the dialog.

Authentication in v1.3.0:

• Your client sends the token via Authorization: Bearer YOUR_TOKEN
• No separate API Key and API Secret are needed
• One token per client (you can generate multiple tokens for different clients)

If you lose the token, generate a new one from the API Keys tab.

Previous method (v1.1.x)

Still works. In v1.3.0 the setup changed to Bearer tokens. If you are on v1.1.x, this is how authentication worked: go to Addons > MCP Server > API Keys, generate an API Key. An API Secret was shown once at creation. Then you set the MCP_API_KEY environment variable in your client config:

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-remote",
        "https://your-whmcs.com/modules/addons/mx_mcp/mcp/sse.php"],
      "env": { "MCP_API_KEY": "your-api-key-here" }
    }
  }
}

Part 2: Configure Claude Desktop

The Setup Assistant inside the addon generates the exact config you need. No manual JSON editing required.

Open the Setup Assistant

1.In WHMCS Admin, go to Addons → MCP Server
2.Click the MCP Endpoint tab
3.Select your client from the dropdown (Claude Desktop, Cursor, VS Code, Windsurf, etc.)
4.The assistant shows the ready-to-use JSON config with your endpoint and token pre-filled

Paste Config into Claude Desktop

Find the Claude Desktop 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

Copy the config from the Setup Assistant and paste it into that file. The config looks like this:

{
  "mcpServers": {
    "whmcs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-whmcs.com/modules/addons/mx_mcp/mcp.php",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Claude Desktop requires Node.js

Claude Desktop uses npx mcp-remote as a bridge to connect to HTTP-based MCP servers. Node.js must be installed on your machine for this to work. Download Node.js →

Restart Claude Desktop

Close completely (Cmd+Q on Mac, Alt+F4 on Windows) and reopen. Claude will connect to your WHMCS automatically.

Dedicated Claude Desktop guide

The integrations page has a detailed step-by-step guide specifically for Claude Desktop, including screenshots.

View Claude Desktop guide →

Other AI Clients (Codex, Cursor, Windsurf, etc.)

MCP Server v1.3.0 connects via HTTP Streamable. Cursor, VS Code, Windsurf, and Codex Desktop support this natively. No Node.js needed on your machine.

Get the exact config for your client from the Setup Assistant: Addons → MCP Server → MCP Endpoint tab. Configs for all major clients are below for reference.

OpenAI Codex Desktop

macOS only (Apple Silicon). Config file:

~/.codex/config.toml

[mcp_servers.whmcs]
url = "https://your-whmcs.com/modules/addons/mx_mcp/mcp.php"

[mcp_servers.whmcs.headers]
Authorization = "Bearer YOUR_TOKEN"

TOML format (not JSON). Download Codex Desktop →

Cursor

Config file location:

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

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-whmcs.com/modules/addons/mx_mcp/mcp.php",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

No Node.js required. Cursor connects directly via HTTP.

Windsurf

Config file:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-whmcs.com/modules/addons/mx_mcp/mcp.php",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

No Node.js required. Windsurf connects directly via HTTP.

Cline (VS Code Extension)

Config file:

.vscode/mcp.json

{
  "servers": {
    "whmcs": {
      "type": "http",
      "url": "https://your-whmcs.com/modules/addons/mx_mcp/mcp.php",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

No Node.js required. VS Code connects directly via HTTP.

Other MCP Clients

Any client that supports HTTP Streamable MCP can connect using the endpoint URL and a Authorization: Bearer YOUR_TOKEN header. Check your client's documentation for the config file location.

Part 3: Test the Connection

Test 1: Verify Connection

Open your AI client and look for the MCP connection indicator.

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

Test 2: First Query

Type this:

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

Your AI client doesn't show MCP Servers connected

•Check config file is saved correctly
•For Claude Desktop: verify Node.js is installed (run node --version in terminal)
•Check Claude Desktop logs at ~/Library/Logs/Claude/ (Claude Desktop only)
•Restart Claude Desktop completely

Your AI client says it doesn't have access to WHMCS

•Verify WHMCS URL ends with /modules/addons/mx_mcp/mcp.php
•Check Bearer token is copied correctly (no extra spaces)
•Test the endpoint manually with curl: curl -H "Authorization: Bearer YOUR_TOKEN" https://your-whmcs.com/modules/addons/mx_mcp/mcp.php
•Check addon is activated in WHMCS

Error: "Module license is invalid or expired"

•Go to WHMCS Admin → Configuration → 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: "Unauthorized" or 401 response

•Go to WHMCS Admin → Addons → MCP Server → API Keys tab
•Verify your credential exists and is active
•Generate a new Bearer token if needed
•Make sure the Authorization header is formatted exactly as: Bearer YOUR_TOKEN

Not all tools are showing (or tools disappear after a while)

•Claude Desktop caches the tool list at startup. Restart the app completely to reload all tools.
•In Claude Desktop: go to Developer menu → Reload MCP Configuration.
•On Windows, if tools still disappear: close Claude Desktop, delete the Cache and Code Cache folders inside %AppData%LocalAnthropicClaude, then reopen.
•This is a Claude Desktop limitation and does not affect Cursor, VS Code, or other clients.

Contact Support Review Checklist

Tools Reference

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

Client Management

4 tools

Products & Services

9 tools

Order Management

6 tools

Invoice Management

4 tools

Quote Management

6 tools

Support Tickets

4 tools

Proposals

6 tools

Business Metrics

5 tools

System

1 tool

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 45 tools above →Setup guides for ChatGPT, n8n, Cursor, and more →