WHMCS MCP Server

WHMCS MCP 服务

面向生产环境的 WHMCS AI 集成。 将 ChatGPT、Claude 和 Cursor 直接连接到您的 WHMCS 安装，通过自然语言管理客户、发票、工单和服务。

You: "Send a payment reminder to all clients with overdue invoices over $50"
AI:  Fetching overdue invoices... Found 12. Sending reminder emails... Done.

---

前提条件 — WHMCS API 设置

运行安装程序前，你需要一个具备适当权限的 WHMCS API 凭据。

1. 创建 API 角色

在 WHMCS Admin 中：Setup → Staff Management → API Roles → Add Role

根据你对 AI 的信任程度，选择一个权限预设：

最低权限（只读 — AI 可以查看，但无法操作）： GetClients GetClientsDetails GetClientsProducts GetClientsDomains GetClientsAddons GetClientGroups GetContacts GetEmails GetInvoice GetInvoices GetOrders GetOrderStatuses GetProducts GetTicket GetTickets GetSupportDepartments GetQuotes GetCredits GetTransactions GetStats GetActivityLog GetCancelledPackages GetEmailTemplates GetCurrencies GetPaymentMethods GetHealthStatus GetProductGroups GetRegistrars GetServers GetAffiliates GetAnnouncements GetSupportStatuses GetTicketCounts GetTicketPredefinedCats GetAdminUsers GetToDoItems GetToDoItemStatuses GetStaffOnline DomainWhois DomainGetNameservers DomainGetLockingStatus GetTLDPricing GetPromotions GetProjects GetProject

最高权限（完全访问 — AI 可以执行任何操作）： 以上所有权限，以及： AddClient UpdateClient AddClientNote AddContact UpdateContact CreateInvoice AddInvoicePayment AddOrder AcceptOrder CancelOrder OpenTicket AddTicketReply UpdateTicket CreateQuote UpdateQuote SendQuote AcceptQuote DeleteQuote AddCredit ApplyCredit AddBillableItem SendEmail UpdateClientProduct ModuleSuspend ModuleUnsuspend ModuleTerminate ModuleCreate UpgradeProduct DomainRegister DomainTransfer DomainRenew DomainUpdateNameservers DomainUpdateLockingStatus DomainToggleIdProtect FraudOrder PendingOrder UpdateInvoice ModuleChangePw LogActivity AddTicketNote AffiliateActivate CreateProject UpdateProject AddProjectTask UpdateProjectTask DeleteProjectTask AddProjectMessage StartTaskTimer EndTaskTimer

项目管理工具：list_projects 到 end_task_timer 的工具还要求 WHMCS Project Management 插件处于启用状态（Setup → Addon Modules），无论 API 角色权限如何。

域名写入权限：register_domain、transfer_domain 和 renew_domain 分别需要 DomainRegister、DomainTransfer 和 DomainRenew。请注意，Domain 前缀在前 — RegisterDomain / TransferDomain / RenewDomain 并非有效的 WHMCS 权限 键，授予这些权限时会被静默忽略。如果域名工具返回 HTTP 403，说明你的角色缺少相应的 权限。如果你要从 2.3.1 或更早版本升级，请参阅 2.3.2 更新日志条目 — 你需要使用正确的名称重新授予这三项权限。

**提示：**先使用最低权限，仅在需要时添加写入权限。如果 AI 客户端失控或收到有问题的提示词，这样可以限制影响范围。

2. 设置 API 访问密钥（推荐）

访问密钥可以完全绕过 IP 限制 — 由于 MCP 服务的出站 IP 可能变化（Docker 重启、服务器迁移等），因此推荐使用这种方式。

将以下行添加到 WHMCS 根目录下的 configuration.php：

$api_access_key = 'your-secret-passphrase';

允许使用的字符：字母、数字以及 ! @ # $ % . ( ) * [ ] - _

然后在 .env 或 Portainer stack 中将 WHMCS_ACCESS_KEY 设置为相同的值。

3. 创建 API 凭据

Setup → Staff Management → API Credentials → Generate New Credential

• Role：选择刚创建的角色
• Allowed IPs：使用访问密钥时留空（推荐），或者输入服务器 IP 以使用基于 IP 的限制
• 复制 Identifier 和 Secret — 安装时需要使用它们

---

快速开始 — 不到 5 分钟即可运行

二进制文件（无需 Docker）：

curl -fsSL https://daddar.io/whmcs-mcp/install.sh | sudo bash

系统会提示你输入 WHMCS 凭据和许可证密钥，将二进制文件安装到 /usr/local/bin，并注册 systemd 服务。

Docker（建议用于已运行 Docker 的服务器）：

curl -fsSL https://daddar.io/whmcs-mcp/install-docker.sh | bash

系统会提示你输入凭据，写入 .env，并通过 Docker Compose 启动整套服务。

---

获取许可证

在 daddar.io/store/ai-tools/whmcs-mcp 购买许可证 — 完成结账后，许可证密钥会显示在客户端门户中。按提示将其粘贴到 setup.sh。

没有许可证？首次运行时会自动开始 14 天免费试用。

---

你可以做什么

98 个 WHMCS 工具

类别	工具
客户	get_client list_clients add_client update_client get_client_details get_client_groups get_client_emails get_client_domains get_client_addons add_client_note
发票	get_invoice list_invoices create_invoice add_invoice_payment get_overdue_invoices get_transactions update_invoice
订单	add_order get_orders accept_order cancel_order get_order_statuses fraud_order pending_order
服务	list_services update_service upgrade_product module_create module_suspend module_unsuspend module_terminate get_cancelled_packages
工单	get_ticket list_tickets open_ticket add_ticket_reply update_ticket get_support_departments add_ticket_note get_support_statuses get_ticket_counts get_ticket_predefined_categories
报价	get_quotes create_quote send_quote accept_quote update_quote delete_quote
联系人	get_contacts add_contact update_contact
额度	get_credits add_credit apply_credit
账单	add_billable_item get_payment_methods get_currencies
电子邮件	send_email get_email_templates
产品	get_products get_product_groups create_product
域名	register_domain transfer_domain renew_domain get_domain_whois get_domain_nameservers update_domain_nameservers get_domain_lock_status update_domain_lock_status update_domain_donotrenew get_tld_pricing
管理	get_admin_users get_staff_online get_whmcs_details log_activity get_activity_log
联盟会员	get_affiliates activate_affiliate
促销	get_promotions
服务器	get_servers module_change_password
系统	get_health_status get_todo_items get_todo_item_statuses get_announcements get_registrars get_stats
报告	get_stats get_activity_log get_transactions
项目	list_projects get_project create_project update_project add_project_task update_project_task delete_project_task add_project_message start_task_timer end_task_timer — 需要启用 WHMCS Project Management 插件

所有工具均支持 dryRun 模式，可在进行更改前预览将要执行的操作。

24 个实时资源

资源是只读数据端点，AI 客户端可通过 whmcs:// URI 订阅。数据由 TTL 为 60 秒的缓存提供。

URI	描述
whmcs://stats	实时系统统计数据（收入、客户数量、发票总额）
whmcs://health	服务运行状况
whmcs://system/info	WHMCS 安装详情（版本、PHP、数据库）
whmcs://products	完整的产品和服务目录
whmcs://product-groups	产品组及产品数量
whmcs://tld-pricing	域名 TLD 注册、转移和续费价格
whmcs://promotions	有效促销和优惠券代码
whmcs://order-statuses	可用的订单状态值
whmcs://currencies	已配置的货币及汇率
whmcs://payment-methods	已启用的支付网关模块
whmcs://registrars	已配置的域名注册商模块
whmcs://servers	配置服务器
whmcs://client-groups	客户组定义
whmcs://affiliates	已注册的联盟营销账户
whmcs://email-templates	电子邮件模板库
whmcs://announcements	已发布的公告
whmcs://support/departments	支持部门
whmcs://support/statuses	可用的工单状态值
whmcs://support/ticket-counts	按部门和状态划分的工单数量
whmcs://support/predefined-categories	预定义的工单回复类别
whmcs://admin/users	管理员用户账户
whmcs://admin/todo	管理员待办事项
whmcs://admin/todo-statuses	可用的待办事项状态值
whmcs://admin/staff-online	当前登录管理区域的员工

18 个工作流提示词

提示词是预先构建的工作流模板，MCP 客户端会将其显示为一键式引导交互。

提示词	描述
new_client	引导创建新的客户账户
new_order	为客户下单并接受产品订单
new_invoice	创建自定义发票，可选择发送
new_quote	起草销售报价，并处理发送和接受流程
ticket_response	加载工单并起草专业的员工回复
client_onboarding	完整的账户入门审核清单
fraud_investigation	对可疑订单进行安全审计
bulk_invoice_reminder	查找逾期发票并发送付款提醒
revenue_report	MRR、未结款项和已付款项的财务明细
client_health_check	深入的账户评分卡（服务、账单、支持）
domain_expiry_audit	标记存在风险的域名并起草续费提醒
new_product_setup	分步产品配置指南
churn_risk_report	按风险排序的客户流失风险表及建议措施
support_queue_triage	按优先级排序的工单队列及快速见效建议
affiliate_performance	优秀推广者、佣金和激活差距
service_renewal_forecast	未来 N 个月的续费收入预测
addon_upsell_opportunities	检测缺少的附加组件并生成追加销售报价
promo_effectiveness	优惠码使用情况、收入影响和到期分析

与其他 WHMCS MCP 服务对比

功能	WHMCS MCP Server（我们）	scarecr0w12/whmcs-mcp-tool	MX Modules
工具	86	~50	~20
HTTP 传输（ChatGPT、Claude 远程）	支持	不支持 — 仅 stdio	支持
身份验证	OAuth 2.0 PKCE + bearer tokens	无	仅静态令牌
一键安装	支持（curl | bash）	手动（克隆 + npm）	手动
实时 Webhook 推送	支持	不支持	不支持
审计日志	支持	不支持	不支持
Prometheus 指标	支持	不支持	不支持
速率限制	支持	不支持	不支持
每个工具均支持 dryRun 模式	支持	不支持	不支持
试用期	免费 14 天	永久免费（MIT）	无
商业支持	支持	无	有限
许可证	商业	MIT	商业

---

支持的 AI 客户端

客户端	传输方式	身份验证
ChatGPT（通过 GPT Actions）	HTTP	Bearer token 或 OAuth 2.0
Claude Desktop	HTTP	Bearer token 或 OAuth 2.0
Cursor IDE	stdio 或 HTTP	Bearer token 或 OAuth 2.0
任何兼容 MCP 的客户端	HTTP	Bearer token 或 OAuth 2.0

---

安全性

• OAuth 2.0 PKCE — 符合行业标准的授权方式，使用短时令牌并支持刷新
• Bearer token 模式 — 适用于单租户部署的简易 API 密钥配置
• 速率限制 — 按 IP 和令牌实施控制（可配置）
• 审计日志 — 记录每个通过身份验证的请求，包含客户端 ID、方法和时间戳
• Helmet.js — 安全标头（CSP、HSTS、X-Frame-Options 等）
• 输入清理 — 纵深防御，抵御注入攻击
• 强制使用 HTTPS — 在生产环境中拒绝纯 HTTP
• Docker secrets — 如果 /run/secrets/ 存在，则从中读取凭据

---

配置

环境变量

将 .env.example 复制为 .env，并填写相应值。

必填项：

变量	说明
WHMCS_API_URL	你的 WHMCS URL，例如 https://billing.example.com
WHMCS_IDENTIFIER	WHMCS API 标识符
WHMCS_SECRET	WHMCS API 密钥

许可证：

变量	说明	默认值
LICENSE_KEY	你从 daddar.io 获取的许可证密钥	（自动开始 14 天免费试用）

身份验证：

变量	说明	默认值
MCP_OAUTH_ADMIN_PASSWORD	启用 OAuth PKCE 流程的 /authorize 授权界面	（未设置 — 授权界面已禁用）
MCP_OAUTH_SESSION_SECRET	用于签署 OAuth CSRF 会话 Cookie 的密钥。使用 openssl rand -hex 32 生成。	（自动生成临时值 — 生产环境中请设置此项）
MCP_AUTH_TOKENS_FILE	Bearer token 存储文件的路径	/app/data/tokens.json

注意（v2.1.0）： MCP_AUTH_MODE 和 MCP_REQUIRE_AUTH 已移除。服务始终运行完整的身份验证栈 — 每种配置均支持 Bearer token 和 OAuth。HTTP 模式下始终强制进行身份验证。

网络 / 代理：

变量	说明	默认值
MCP_TRUST_PROXY	当服务运行在终止 TLS 的反向代理（Traefik、nginx 等）之后时，设为 true。启用对 X-Forwarded-* 标头的信任，以便正确检测 IP 并强制使用 HTTPS。	false （在 v2.2.0 中更改 — 生产环境中请显式设置）

可观测性（可选）：

变量	说明	默认值
MCP_METRICS_ENABLED	启用 Prometheus 指标端点	true
MCP_METRICS_PORT	/metrics 端点的端口	9090
PUSHGATEWAY_URL	用于推送指标的 Prometheus Pushgateway URL	（未设置）
PUSHGATEWAY_USER	Pushgateway 的 HTTP Basic Auth 用户名	（未设置）
PUSHGATEWAY_PASSWORD	Pushgateway 的 HTTP Basic Auth 密码	（未设置）

Webhooks（可选）：

变量	说明
WHMCS_WEBHOOK_SECRET	与你的 WHMCS PHP 钩子共享的 HMAC 密钥

所有选项请参阅 .env.example。

---

连接 AI 客户端

Cursor IDE

Bearer token（简易方式）： 添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

OAuth（新版应用界面）： 通过 Cursor 的“New App”使用 OAuth 添加时，服务必须设置 MCP_CLIENT_REGISTRATION_SECRET（在 Portainer 或 .env 中）。使用 openssl rand -hex 24 生成，在服务端设置，然后在 Cursor 的高级 OAuth 设置中“Client registration secret”（或类似选项）下输入相同的值。这样 Cursor 就能通过动态客户端注册自行注册。

或者使用本地 stdio 模式：

{
  "mcpServers": {
    "whmcs": {
      "command": "node",
      "args": ["/path/to/whmcs-mcp/dist/index.js"],
      "env": {
        "WHMCS_API_URL": "https://your-whmcs.example.com",
        "WHMCS_IDENTIFIER": "your-identifier",
        "WHMCS_SECRET": "your-secret"
      }
    }
  }
}

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "whmcs": {
      "url": "https://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

ChatGPT（GPT Actions）

将你的 GPT Action 架构指向 https://your-server:3100/mcp。多用户设置请使用 OAuth 2.0 模式。

---

实时 Webhook 推送

实时接收推送到 AI 的 WHMCS 事件，包括新工单、发票和逾期付款。

设置说明请参阅 docs/WEBHOOKS.md。

---

部署

Docker Compose（推荐）

docker compose -f docker-compose.marketplace.yml up -d

生成令牌：

docker exec -it whmcs-mcp node dist/scripts/auth-cli.js generate \
  --name "My AI" --scopes "mcp:read,mcp:write"

Kubernetes

请参阅 k8s-deployment.yaml 和 DEPLOYMENT.md。

位于反向代理之后（nginx / Caddy / Traefik）

从 docker-compose.marketplace.yml 中移除 ports 块，并将代理指向 whmcs-mcp:3100。请参阅该文件中的注释。

---

可观测性

• 健康检查： GET /health
• 就绪状态： GET /ready
• Prometheus 指标： 端口 9090（可通过 MCP_METRICS_PORT 配置）

关键指标：whmcs_mcp_requests_total、whmcs_mcp_request_duration_seconds、whmcs_mcp_active_sessions、whmcs_mcp_auth_total

---

支持与许可

• 购买 / 管理许可证： daddar.io/store/ai-tools/whmcs-mcp
• 文档： 本仓库 + DEPLOYMENT.md + docs/WEBHOOKS.md
• 支持： [email protected]
• 安全问题： SECURITY.md

版权所有 © 2026 Daddario Tech Solutions。保留所有权利。请参阅 LICENSE。