WAHA MCP Server

Instructions

Implementation Reference

• src/index.ts:2061-2086 (handler)

  MCP tool handler that extracts parameters, validates inputs, calls WAHAClient.updateGroupDescription, and returns success message.
  private async handleUpdateGroupDescription(args: any) { const groupId = args.groupId; const description = args.description; if (!groupId) { throw new Error("groupId is required"); } if (!description) { throw new Error("description is required"); } await this.wahaClient.updateGroupDescription({ groupId, description, }); return { content: [ { type: "text", text: `Successfully updated group ${groupId} description.`, }, ], }; }
• src/index.ts:652-669 (schema)

  Input schema definition for the tool, specifying required groupId and description parameters.
  { 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"], }, },
• src/index.ts:1105-1106 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement that routes to the handler.
  case "waha_update_group_description": return await this.handleUpdateGroupDescription(args);
• src/client/waha-client.ts:921-943 (helper)

  Underlying WAHAClient method that makes the HTTP PUT request to update the group description via WAHA API.
  async updateGroupDescription(params: { groupId: string; description: string; }): Promise<void> { const { groupId, description } = params; if (!groupId) { throw new WAHAError("groupId is required"); } if (!description) { throw new WAHAError("description is required"); } const endpoint = `/api/${this.session}/groups/${encodeURIComponent(groupId)}/description`; const body = { description }; await this.request<void>(endpoint, { method: "PUT", body: JSON.stringify(body), }); }
• src/index.ts:61-1043 (registration)

  Overall tool registration in ListToolsRequestHandler that includes this tool's metadata and schema.
  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: {}, }, }, ], }; });