whmcs-mcp-server

Instructions

Implementation Reference

• src/whmcs-client.ts:170-203 (handler)

  Core implementation of the whmcs_add_client tool: calls WHMCS 'AddClient' API action via the generic call() method, handling parameters and response.

  async addClient(params: {
      firstname: string;
      lastname: string;
      email: string;
      address1: string;
      city: string;
      state: string;
      postcode: string;
      country: string;
      phonenumber: string;
      password2: string;
      companyname?: string;
      address2?: string;
      currency?: number;
      clientip?: string;
      language?: string;
      groupid?: number;
      securityqid?: number;
      securityqans?: string;
      notes?: string;
      cardtype?: string;
      cardnum?: string;
      expdate?: string;
      startdate?: string;
      issuenumber?: string;
      cvv?: string;
      noemail?: boolean;
      skipvalidation?: boolean;
  }) {
      return this.call<WhmcsApiResponse & {
          clientid: number;
          owner_user_id: number;
      }>('AddClient', params);
  }

• src/index.ts:91-121 (registration)

  MCP tool registration for 'whmcs_add_client', including schema definition and thin handler delegating to WhmcsApiClient.addClient()

      'whmcs_add_client',
      {
          title: 'Add Client',
          description: 'Create a new client in WHMCS',
          inputSchema: {
              firstname: z.string().describe('Client first name'),
              lastname: z.string().describe('Client last name'),
              email: z.string().email().describe('Client email address'),
              address1: z.string().describe('Street address'),
              city: z.string().describe('City'),
              state: z.string().describe('State/Province'),
              postcode: z.string().describe('Postal/ZIP code'),
              country: z.string().describe('Country (2-letter ISO code)'),
              phonenumber: z.string().describe('Phone number'),
              password2: z.string().describe('Password for the client account'),
              companyname: z.string().optional().describe('Company name'),
              address2: z.string().optional().describe('Address line 2'),
              currency: z.number().optional().describe('Currency ID'),
              language: z.string().optional().describe('Client language'),
              groupid: z.number().optional().describe('Client group ID'),
              notes: z.string().optional().describe('Admin notes'),
              noemail: z.boolean().optional().describe('Do not send welcome email'),
          },
      },
      async (params) => {
          const result = await whmcsClient.addClient(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/whmcs-client.ts:29-63 (helper)

  Generic low-level API caller used by all tools including addClient: handles authentication, param flattening, HTTP POST to /includes/api.php, error handling, and JSON response parsing.

  async call<T extends WhmcsApiResponse>(action: string, params: Record<string, unknown> = {}): Promise<T> {
      const url = `${this.config.apiUrl.replace(/\/$/, '')}/includes/api.php`;
      
      const postData: Record<string, string> = {
          identifier: this.config.apiIdentifier,
          secret: this.config.apiSecret,
          action: action,
          responsetype: 'json',
          ...this.flattenParams(params)
      };
  
      if (this.config.accessKey) {
          postData.accesskey = this.config.accessKey;
      }
  
      const response = await fetch(url, {
          method: 'POST',
          headers: {
              'Content-Type': 'application/x-www-form-urlencoded',
          },
          body: new URLSearchParams(postData).toString(),
      });
  
      if (!response.ok) {
          throw new Error(`WHMCS API request failed: ${response.status} ${response.statusText}`);
      }
  
      const data = await response.json() as T;
      
      if (data.result === 'error') {
          throw new Error(`WHMCS API error: ${data.message || 'Unknown error'}`);
      }
  
      return data;
  }