Integration Guide
Claude Desktop + WHMCS
Connect Claude Desktop to WHMCS in under 10 minutes
Estimated time: 10 minutes · Transport: STDIO
Quick Reference
- Min Version
- Claude Desktop 1.0+
- Transport
- STDIO via npx bridge
- Public URL
- Not required
- Node.js
- Required
- Free Tier MCP
- Yes
- Concurrent Tools
- Up to 5 tool calls per turn
- Avg Response Time
- 2-4 seconds for simple queries, 8-15 seconds for multi-tool operations
Prerequisites
- WHMCS 8.0 or higher with admin access
- MCP Server addon installed and activated (installation guide)
- Claude Desktop installed (download here)
- Node.js installed. Claude Desktop uses npx to run mcp-remote as a STDIO-to-HTTP bridge. This is a Claude Desktop limitation. The addon itself does not require Node.js.
Step 1: Generate a Bearer Token
- Go to your WHMCS admin panel
- Navigate to Addons > MCP Server
- Go to API Keys and click Generate New Key
- Copy the Bearer token and store it securely. You will need it in the next step.
Important: The Bearer token is shown only once when generated. If you lose it, regenerate it from Addons > MCP Server > API Keys.
Step 2: Configure Claude Desktop
Open the Claude Desktop configuration file. The location depends on your operating system:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add the following configuration (replace the URL and Bearer token with your own):
{
"mcpServers": {
"whmcs": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-whmcs.com/modules/addons/mx_mcp/mcp.php",
"--header",
"Authorization:Bearer YOUR_BEARER_TOKEN"
]
}
}
}Step 3: Test the Connection
- Close Claude Desktop completely (quit the application)
- Reopen Claude Desktop
- Start a new conversation
- Type:
Get WHMCS system status - If the connection is working, you should see system information from your WHMCS installation
Success! If you see WHMCS system info, the connection is working. Try more queries like “List all active clients” or “Show overdue invoices”.
Troubleshooting
“MCP server not found”
- Verify the config file path is correct for your OS
- Ensure the JSON is valid (no trailing commas, proper quotes)
- Make sure Node.js is installed and npx is available in your PATH
- Restart Claude Desktop completely (not just close the window)
“Connection refused” or timeout
- Verify your WHMCS URL is correct and accessible from your machine
- Check that the MCP Server addon is activated in WHMCS
- Check that your Bearer token is correct. Regenerate it from Addons > MCP Server > API Keys if needed.
- Check if your WHMCS has HTTPS enabled (required for remote connections)
“Permission denied”
- Your Bearer token may not have the required permissions
- Go to Addons > MCP Server in WHMCS and check API key permissions
- Ensure the key has access to the tools you are trying to use
Upgrading from v1.1.x?
If you set up the MCP Server before v1.3.0, the authentication method changed. Here is what is different and how to update your config.
Previous method (v1.1.x)
Still works. In v1.3.0, authentication changed from API Keys to Bearer tokens, and the endpoint changed from sse.php to mcp.php. If you are still on v1.1.x, this is how it was configured:
{
"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" }
}
}
}To upgrade: replace the config above with the new Bearer token format shown in Step 2, then regenerate a Bearer token from Addons > MCP Server > API Keys.