WAHA MCP Server

Instructions

Implementation Reference

• src/index.ts:939-957 (registration)

  Tool registration in ListToolsRequestSchema handler, defines name, description, and input schema.

  {
    name: "waha_get_contact_profile_picture",
    description: "Get contact's profile picture URL.",
    inputSchema: {
      type: "object",
      properties: {
        contactId: {
          type: "string",
          description: "Contact ID (format: number@c.us)",
        },
        refresh: {
          type: "boolean",
          description: "Refresh from server (default: false)",
          default: false,
        },
      },
      required: ["contactId"],
    },
  },

• src/index.ts:2516-2537 (handler)

  MCP tool handler function that validates input, calls WAHA client method, and returns formatted URL response.

  private async handleGetContactProfilePicture(args: any) {
    const contactId = args.contactId;
    const refresh = args.refresh || false;
  
    if (!contactId) {
      throw new Error("contactId is required");
    }
  
    const result = await this.wahaClient.getContactProfilePicture({
      contactId,
      refresh,
    });
  
    return {
      content: [
        {
          type: "text",
          text: `Profile picture URL for ${contactId}:\n${result.url}\n${refresh ? '(Refreshed from server)' : '(From cache)'}`,
        },
      ],
    };
  }

• src/client/waha-client.ts:1320-1347 (helper)

  WAHA client helper method that constructs API endpoint and makes HTTP GET request to retrieve contact profile picture URL.

  async getContactProfilePicture(params: {
    contactId: string;
    refresh?: boolean;
  }): Promise<{ url: string }> {
    const { contactId, refresh } = params;
  
    if (!contactId) {
      throw new WAHAError("contactId is required");
    }
  
    const queryParams: Record<string, any> = { 
      contactId,
      session: this.session
    };
    if (refresh !== undefined) {
      queryParams.refresh = refresh;
    }
  
    const queryString = this.buildQueryString(queryParams);
    const endpoint = `/api/contacts/profile-picture${queryString}`;
  
    const response = await this.request<{ profilePictureURL?: string; url?: string }>(endpoint, {
      method: "GET",
    });
  
    // Handle both response formats: profilePictureURL (contacts) or url (chats)
    return { url: response.profilePictureURL || response.url || '' };
  }