WAHA MCP Server

Instructions

Implementation Reference

• src/index.ts:1916-1937 (handler)

  MCP tool handler for 'waha_get_group_picture'. Extracts parameters, validates groupId, calls underlying WAHAClient.getGroupPicture method, and returns formatted response with picture URL.
  private async handleGetGroupPicture(args: any) { const groupId = args.groupId; const refresh = args.refresh || false; if (!groupId) { throw new Error("groupId is required"); } const result = await this.wahaClient.getGroupPicture({ groupId, refresh, }); return { content: [ { type: "text", text: `Group picture URL for ${groupId}:\n${result.url}\n${refresh ? '(Refreshed from server)' : '(From cache)'}`, }, ], }; }
• src/index.ts:562-579 (schema)

  Input schema definition for the 'waha_get_group_picture' tool, including parameters groupId (required) and refresh (optional boolean).
  name: "waha_get_group_picture", description: "Get group profile picture URL.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, refresh: { type: "boolean", description: "Refresh from server (default: false)", default: false, }, }, required: ["groupId"], }, },
• src/index.ts:1046-1157 (registration)

  Registration of tool call handler via setRequestHandler(CallToolRequestSchema), with switch case dispatching 'waha_get_group_picture' to handleGetGroupPicture.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case "waha_get_chats": return await this.handleGetChats(args); case "waha_get_messages": return await this.handleGetMessages(args); case "waha_send_message": return await this.handleSendMessage(args); case "waha_mark_chat_read": return await this.handleMarkChatRead(args); case "waha_delete_message": return await this.handleDeleteMessage(args); case "waha_edit_message": return await this.handleEditMessage(args); case "waha_pin_message": return await this.handlePinMessage(args); case "waha_unpin_message": return await this.handleUnpinMessage(args); case "waha_clear_chat_messages": return await this.handleClearChatMessages(args); case "waha_delete_chat": return await this.handleDeleteChat(args); case "waha_archive_chat": return await this.handleArchiveChat(args); case "waha_unarchive_chat": return await this.handleUnarchiveChat(args); case "waha_mark_chat_unread": return await this.handleMarkChatUnread(args); case "waha_get_chat_picture": return await this.handleGetChatPicture(args); case "waha_send_media": return await this.handleSendMedia(args); case "waha_send_audio": return await this.handleSendAudio(args); case "waha_send_location": return await this.handleSendLocation(args); case "waha_send_contact": return await this.handleSendContact(args); case "waha_react_to_message": return await this.handleReactToMessage(args); case "waha_star_message": return await this.handleStarMessage(args); case "waha_get_groups": return await this.handleGetGroups(args); case "waha_get_group_info": return await this.handleGetGroupInfo(args); case "waha_get_group_picture": return await this.handleGetGroupPicture(args); case "waha_set_group_picture": return await this.handleSetGroupPicture(args); case "waha_delete_group_picture": return await this.handleDeleteGroupPicture(args); case "waha_create_group": return await this.handleCreateGroup(args); case "waha_update_group_subject": return await this.handleUpdateGroupSubject(args); case "waha_update_group_description": return await this.handleUpdateGroupDescription(args); case "waha_leave_group": return await this.handleLeaveGroup(args); case "waha_get_group_participants": return await this.handleGetGroupParticipants(args); case "waha_add_group_participants": return await this.handleAddGroupParticipants(args); case "waha_remove_group_participants": return await this.handleRemoveGroupParticipants(args); case "waha_promote_group_admin": return await this.handlePromoteGroupAdmin(args); case "waha_demote_group_admin": return await this.handleDemoteGroupAdmin(args); case "waha_get_group_invite_code": return await this.handleGetGroupInviteCode(args); case "waha_revoke_group_invite_code": return await this.handleRevokeGroupInviteCode(args); case "waha_join_group": return await this.handleJoinGroup(args); case "waha_get_group_join_info": return await this.handleGetGroupJoinInfo(args); case "waha_set_group_messages_admin_only": return await this.handleSetGroupMessagesAdminOnly(args); case "waha_set_group_info_admin_only": return await this.handleSetGroupInfoAdminOnly(args); case "waha_get_groups_count": return await this.handleGetGroupsCount(args); case "waha_get_contact": return await this.handleGetContact(args); case "waha_get_all_contacts": return await this.handleGetAllContacts(args); case "waha_check_contact_exists": return await this.handleCheckContactExists(args); case "waha_get_contact_about": return await this.handleGetContactAbout(args); case "waha_get_contact_profile_picture": return await this.handleGetContactProfilePicture(args); case "waha_get_chat_picture": return await this.handleGetChatPicture(args); case "waha_block_contact": return await this.handleBlockContact(args); case "waha_unblock_contact": return await this.handleUnblockContact(args); case "waha_get_presence": return await this.handleGetPresence(args); case "waha_subscribe_presence": return await this.handleSubscribePresence(args); case "waha_set_presence": return await this.handleSetPresence(args); case "waha_get_all_presence": return await this.handleGetAllPresence(args); default:
• src/client/waha-client.ts:791-814 (handler)

  Core WAHA client implementation that performs HTTP GET request to WAHA API endpoint /api/{session}/groups/{groupId}/picture to retrieve group picture URL.
  async getGroupPicture(params: { groupId: string; refresh?: boolean; }): Promise<{ url: string }> { const { groupId, refresh } = params; if (!groupId) { throw new WAHAError("groupId is required"); } const queryParams: Record<string, any> = {}; if (refresh !== undefined) { queryParams.refresh = refresh; } const queryString = this.buildQueryString(queryParams); const endpoint = `/api/${this.session}/groups/${encodeURIComponent( groupId )}/picture${queryString}`; return this.request<{ url: string }>(endpoint, { method: "GET", }); }
• src/index.ts:61-1043 (registration)

  Tool list registration in ListToolsRequestSchema handler, advertises 'waha_get_group_picture' tool with its schema to MCP clients.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "waha_get_chats", description: "Get overview of recent WhatsApp chats. Returns chat ID, name, last message preview, and unread count. Default limit is 10 chats.", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Number of chats to retrieve (default: 10, max: 100)", default: 10, }, offset: { type: "number", description: "Offset for pagination", }, chatIds: { type: "array", items: { type: "string" }, description: "Optional filter for specific chat IDs (format: number@c.us)", }, }, }, }, { name: "waha_get_messages", description: "Get messages from a specific WhatsApp chat. Returns message content, sender, timestamp, and status. Default limit is 10 messages.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID to get messages from (format: number@c.us for individual, number@g.us for group)", }, limit: { type: "number", description: "Number of messages to retrieve (default: 10, max: 100)", default: 10, }, offset: { type: "number", description: "Offset for pagination", }, downloadMedia: { type: "boolean", description: "Download media files (default: false)", default: false, }, }, required: ["chatId"], }, }, { name: "waha_send_message", description: "Send a text message to a WhatsApp chat. Returns message ID and delivery timestamp.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID to send message to (format: number@c.us)", }, text: { type: "string", description: "Message text to send", }, replyTo: { type: "string", description: "Optional: Message ID to reply to", }, linkPreview: { type: "boolean", description: "Enable link preview (default: true)", default: true, }, }, required: ["chatId", "text"], }, }, { name: "waha_mark_chat_read", description: "Mark messages in a chat as read. Can specify number of recent messages or time range in days.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID to mark as read (format: number@c.us)", }, messages: { type: "number", description: "Number of recent messages to mark as read (default: 30)", default: 30, }, days: { type: "number", description: "Mark messages from last N days as read (default: 7)", default: 7, }, }, required: ["chatId"], }, }, { name: "waha_delete_message", description: "Delete a specific message from a chat. This is a destructive operation and cannot be undone.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, messageId: { type: "string", description: "Message ID to delete (format: {fromMe}_{chat}_{message_id}[_{participant}])", }, }, required: ["chatId", "messageId"], }, }, { name: "waha_edit_message", description: "Edit a sent message in a chat. Only works for messages sent by the bot.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, messageId: { type: "string", description: "Message ID to edit", }, text: { type: "string", description: "New message text", }, linkPreview: { type: "boolean", description: "Enable link preview (default: true)", default: true, }, linkPreviewHighQuality: { type: "boolean", description: "Enable high quality link preview (default: false)", default: false, }, }, required: ["chatId", "messageId", "text"], }, }, { name: "waha_pin_message", description: "Pin a message in a chat. Pinned messages appear at the top of the chat.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, messageId: { type: "string", description: "Message ID to pin", }, duration: { type: "number", description: "Pin duration in seconds (default: 86400 = 24 hours)", default: 86400, }, }, required: ["chatId", "messageId"], }, }, { name: "waha_unpin_message", description: "Unpin a message in a chat.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, messageId: { type: "string", description: "Message ID to unpin", }, }, required: ["chatId", "messageId"], }, }, { name: "waha_clear_chat_messages", description: "Clear all messages from a chat. WARNING: This is a destructive operation that cannot be undone.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_delete_chat", description: "Delete a chat completely. WARNING: This is a destructive operation that cannot be undone.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_archive_chat", description: "Archive a chat. Archived chats are hidden from the main chat list.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_unarchive_chat", description: "Unarchive a chat. Moves the chat back to the main chat list.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_mark_chat_unread", description: "Mark a chat as unread. This adds an unread indicator to the chat.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_get_chat_picture", description: "Get the profile picture URL for a chat. Uses 24-hour cache by default.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, refresh: { type: "boolean", description: "Refresh from server instead of using cache (default: false)", default: false, }, }, required: ["chatId"], }, }, { name: "waha_send_media", description: "Send media files (images, videos, or documents) to a WhatsApp chat. Supports URL or base64 data.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, mediaType: { type: "string", enum: ["image", "video", "document"], description: "Type of media to send", }, fileUrl: { type: "string", description: "URL of the file to send (use either fileUrl or fileData, not both)", }, fileData: { type: "string", description: "Base64 encoded file data (use either fileUrl or fileData, not both)", }, mimetype: { type: "string", description: "MIME type of the file (e.g., 'image/jpeg', 'video/mp4', 'application/pdf')", }, filename: { type: "string", description: "Optional filename for the media", }, caption: { type: "string", description: "Optional caption for the media", }, replyTo: { type: "string", description: "Optional message ID to reply to", }, }, required: ["chatId", "mediaType", "mimetype"], }, }, { name: "waha_send_audio", description: "Send audio/voice messages to a WhatsApp chat. Supports URL or base64 data.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, fileUrl: { type: "string", description: "URL of the audio file to send (use either fileUrl or fileData, not both)", }, fileData: { type: "string", description: "Base64 encoded audio data (use either fileUrl or fileData, not both)", }, mimetype: { type: "string", description: "MIME type of the audio file (e.g., 'audio/ogg', 'audio/mpeg')", }, filename: { type: "string", description: "Optional filename for the audio", }, replyTo: { type: "string", description: "Optional message ID to reply to", }, }, required: ["chatId", "mimetype"], }, }, { name: "waha_send_location", description: "Send location coordinates to a WhatsApp chat.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, latitude: { type: "number", description: "Latitude coordinate", }, longitude: { type: "number", description: "Longitude coordinate", }, title: { type: "string", description: "Optional title/name for the location", }, replyTo: { type: "string", description: "Optional message ID to reply to", }, }, required: ["chatId", "latitude", "longitude"], }, }, { name: "waha_send_contact", description: "Send contact card(s) to a WhatsApp chat using vCard format.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, vcard: { type: "string", description: "vCard formatted contact data (e.g., 'BEGIN:VCARD\\nVERSION:3.0\\nFN:Jane Doe\\nTEL:+1234567890\\nEND:VCARD')", }, replyTo: { type: "string", description: "Optional message ID to reply to", }, }, required: ["chatId", "vcard"], }, }, { name: "waha_react_to_message", description: "Add an emoji reaction to a message. To remove a reaction, send an empty string.", inputSchema: { type: "object", properties: { messageId: { type: "string", description: "Message ID to react to", }, reaction: { type: "string", description: "Emoji to react with (e.g., '👍', '❤️', '😂'). Use empty string to remove reaction.", }, }, required: ["messageId", "reaction"], }, }, { name: "waha_star_message", description: "Star or unstar a message.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, messageId: { type: "string", description: "Message ID to star/unstar", }, star: { type: "boolean", description: "True to star the message, false to unstar", }, }, required: ["chatId", "messageId", "star"], }, }, { name: "waha_get_groups", description: "List all groups with filtering and pagination options.", inputSchema: { type: "object", properties: { sortBy: { type: "string", enum: ["id", "name"], description: "Sort field (default: id)", }, sortOrder: { type: "string", enum: ["asc", "desc"], description: "Sort order (default: asc)", }, limit: { type: "number", description: "Limit results (default: 100, max: 100)", }, offset: { type: "number", description: "Offset for pagination", }, exclude: { type: "array", items: { type: "string" }, description: "Exclude fields like 'participants'", }, }, }, }, { name: "waha_get_group_info", description: "Get detailed information about a specific group.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_get_group_picture", description: "Get group profile picture URL.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, refresh: { type: "boolean", description: "Refresh from server (default: false)", default: false, }, }, required: ["groupId"], }, }, { name: "waha_set_group_picture", description: "Set or update group profile picture.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, fileUrl: { type: "string", description: "URL of the image (use either fileUrl or fileData)", }, fileData: { type: "string", description: "Base64 encoded image data (use either fileUrl or fileData)", }, }, required: ["groupId"], }, }, { name: "waha_delete_group_picture", description: "Remove group profile picture.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_create_group", description: "Create a new WhatsApp group.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Group name", }, participants: { type: "string", description: "JSON array of participants (format: [{'id': 'number@c.us'}, ...])", }, }, required: ["name", "participants"], }, }, { name: "waha_update_group_subject", description: "Change group name/subject.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, subject: { type: "string", description: "New group name", }, }, required: ["groupId", "subject"], }, }, { name: "waha_update_group_description", description: "Update group description.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, description: { type: "string", description: "New group description", }, }, required: ["groupId", "description"], }, }, { name: "waha_leave_group", description: "Leave a group.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID to leave (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_get_group_participants", description: "List all members in a group.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_add_group_participants", description: "Add member(s) to a group. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, participants: { type: "string", description: "JSON array of participants to add (format: [{'id': 'number@c.us'}, ...])", }, }, required: ["groupId", "participants"], }, }, { name: "waha_remove_group_participants", description: "Remove member(s) from a group. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, participants: { type: "string", description: "JSON array of participants to remove (format: [{'id': 'number@c.us'}, ...])", }, }, required: ["groupId", "participants"], }, }, { name: "waha_promote_group_admin", description: "Promote participant(s) to group admin. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, participants: { type: "string", description: "JSON array of participants to promote (format: [{'id': 'number@c.us'}, ...])", }, }, required: ["groupId", "participants"], }, }, { name: "waha_demote_group_admin", description: "Remove admin privileges from participant(s). Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, participants: { type: "string", description: "JSON array of participants to demote (format: [{'id': 'number@c.us'}, ...])", }, }, required: ["groupId", "participants"], }, }, { name: "waha_get_group_invite_code", description: "Get group invite link.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_revoke_group_invite_code", description: "Revoke current invite link and generate a new one. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, }, required: ["groupId"], }, }, { name: "waha_join_group", description: "Join a group using invite code/link.", inputSchema: { type: "object", properties: { code: { type: "string", description: "Invite code or full URL (e.g., 'https://chat.whatsapp.com/...')", }, }, required: ["code"], }, }, { name: "waha_get_group_join_info", description: "Get group information from invite link without joining.", inputSchema: { type: "object", properties: { code: { type: "string", description: "Invite code or full URL", }, }, required: ["code"], }, }, { name: "waha_set_group_messages_admin_only", description: "Toggle whether only admins can send messages. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, adminsOnly: { type: "boolean", description: "True = only admins can send, false = all members can send", }, }, required: ["groupId", "adminsOnly"], }, }, { name: "waha_set_group_info_admin_only", description: "Toggle whether only admins can edit group info. Requires admin privileges.", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "Group ID (format: number@g.us)", }, adminsOnly: { type: "boolean", description: "True = only admins can edit, false = all members can edit", }, }, required: ["groupId", "adminsOnly"], }, }, { name: "waha_get_groups_count", description: "Get total number of groups.", inputSchema: { type: "object", properties: {}, }, }, { name: "waha_get_contact", description: "Get contact information by ID.", inputSchema: { type: "object", properties: { contactId: { type: "string", description: "Contact ID (format: number@c.us)", }, }, required: ["contactId"], }, }, { name: "waha_get_all_contacts", description: "List all contacts with pagination.", inputSchema: { type: "object", properties: { sortBy: { type: "string", enum: ["id", "name"], description: "Sort field (default: id)", }, sortOrder: { type: "string", enum: ["asc", "desc"], description: "Sort order (default: asc)", }, limit: { type: "number", description: "Limit results (default: 100, max: 100)", }, offset: { type: "number", description: "Offset for pagination", }, }, }, }, { name: "waha_check_contact_exists", description: "Check if phone number is registered on WhatsApp.", inputSchema: { type: "object", properties: { phone: { type: "string", description: "Phone number to check (e.g., '1234567890')", }, }, required: ["phone"], }, }, { name: "waha_get_contact_about", description: "Get contact's about/status text.", inputSchema: { type: "object", properties: { contactId: { type: "string", description: "Contact ID (format: number@c.us)", }, }, required: ["contactId"], }, }, { 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"], }, }, { name: "waha_block_contact", description: "Block a contact.", inputSchema: { type: "object", properties: { contactId: { type: "string", description: "Contact ID to block (format: number@c.us)", }, }, required: ["contactId"], }, }, { name: "waha_unblock_contact", description: "Unblock a contact.", inputSchema: { type: "object", properties: { contactId: { type: "string", description: "Contact ID to unblock (format: number@c.us)", }, }, required: ["contactId"], }, }, { name: "waha_get_presence", description: "Get online/offline/typing status for a chat. Auto-subscribes if not already subscribed.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_subscribe_presence", description: "Subscribe to presence updates for a chat.", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, }, required: ["chatId"], }, }, { name: "waha_set_presence", description: "Set your own presence status (online, offline, typing, recording, or paused).", inputSchema: { type: "object", properties: { chatId: { type: "string", description: "Chat ID (format: number@c.us)", }, presence: { type: "string", enum: ["online", "offline", "typing", "recording", "paused"], description: "Presence status to set", }, }, required: ["chatId", "presence"], }, }, { name: "waha_get_all_presence", description: "Get all subscribed presence information.", inputSchema: { type: "object", properties: {}, }, }, ], }; });