WhatsApp MCP Server

Implementation Reference

• src/mcp.ts:398-472 (handler)

  The core handler function for the 'send_message' tool. It logs execution, checks socket availability, normalizes recipient JID, handles errors, calls the sendWhatsAppMessage helper, and returns success/error responses.

  async ({ recipient, message }) => {
    mcpLogger.info(`[MCP Tool] Executing send_message to ${recipient}`);
    if (!sock) {
      mcpLogger.error(
        "[MCP Tool Error] send_message failed: WhatsApp socket is not available.",
      );
      return {
        isError: true,
        content: [
          { type: "text", text: "Error: WhatsApp connection is not active." },
        ],
      };
    }
  
    let normalizedRecipient: string;
    try {
      normalizedRecipient = jidNormalizedUser(recipient);
      if (!normalizedRecipient.includes("@")) {
        throw new Error('JID must contain "@" symbol');
      }
    } catch (normError: any) {
      mcpLogger.error(
        `[MCP Tool Error] Invalid recipient JID format: ${recipient}. Error: ${normError.message}`,
      );
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `Invalid recipient format: "${recipient}". Please provide a valid JID (e.g., number@s.whatsapp.net or group@g.us).`,
          },
        ],
      };
    }
  
    try {
      const result = await sendWhatsAppMessage(
        waLogger,
        sock,
        normalizedRecipient,
        message,
      );
  
      if (result && result.key && result.key.id) {
        return {
          content: [
            {
              type: "text",
              text: `Message sent successfully to ${normalizedRecipient} (ID: ${result.key.id}).`,
            },
          ],
        };
      } else {
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: `Failed to send message to ${normalizedRecipient}. See server logs for details.`,
            },
          ],
        };
      }
    } catch (error: any) {
      mcpLogger.error(
        `[MCP Tool Error] send_message failed for ${recipient}: ${error.message}`,
      );
      return {
        isError: true,
        content: [
          { type: "text", text: `Error sending message: ${error.message}` },
        ],
      };
    }
  },

• src/mcp.ts:390-397 (schema)

  Zod schema defining input parameters for send_message: recipient (string JID) and message (non-empty string).

  {
    recipient: z
      .string()
      .describe(
        "Recipient JID (user or group, e.g., '12345@s.whatsapp.net' or 'group123@g.us')",
      ),
    message: z.string().min(1).describe("The text message to send"),
  },

• src/mcp.ts:388-473 (registration)

  MCP server.tool registration of the 'send_message' tool, specifying name, input schema, and handler function.

  server.tool(
    "send_message",
    {
      recipient: z
        .string()
        .describe(
          "Recipient JID (user or group, e.g., '12345@s.whatsapp.net' or 'group123@g.us')",
        ),
      message: z.string().min(1).describe("The text message to send"),
    },
    async ({ recipient, message }) => {
      mcpLogger.info(`[MCP Tool] Executing send_message to ${recipient}`);
      if (!sock) {
        mcpLogger.error(
          "[MCP Tool Error] send_message failed: WhatsApp socket is not available.",
        );
        return {
          isError: true,
          content: [
            { type: "text", text: "Error: WhatsApp connection is not active." },
          ],
        };
      }
  
      let normalizedRecipient: string;
      try {
        normalizedRecipient = jidNormalizedUser(recipient);
        if (!normalizedRecipient.includes("@")) {
          throw new Error('JID must contain "@" symbol');
        }
      } catch (normError: any) {
        mcpLogger.error(
          `[MCP Tool Error] Invalid recipient JID format: ${recipient}. Error: ${normError.message}`,
        );
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: `Invalid recipient format: "${recipient}". Please provide a valid JID (e.g., number@s.whatsapp.net or group@g.us).`,
            },
          ],
        };
      }
  
      try {
        const result = await sendWhatsAppMessage(
          waLogger,
          sock,
          normalizedRecipient,
          message,
        );
  
        if (result && result.key && result.key.id) {
          return {
            content: [
              {
                type: "text",
                text: `Message sent successfully to ${normalizedRecipient} (ID: ${result.key.id}).`,
              },
            ],
          };
        } else {
          return {
            isError: true,
            content: [
              {
                type: "text",
                text: `Failed to send message to ${normalizedRecipient}. See server logs for details.`,
              },
            ],
          };
        }
      } catch (error: any) {
        mcpLogger.error(
          `[MCP Tool Error] send_message failed for ${recipient}: ${error.message}`,
        );
        return {
          isError: true,
          content: [
            { type: "text", text: `Error sending message: ${error.message}` },
          ],
        };
      }
    },
  );

• src/whatsapp.ts:248-281 (helper)

  Supporting helper function sendWhatsAppMessage that performs the actual message sending via Baileys library sock.sendMessage, with logging and error handling.

  export async function sendWhatsAppMessage(
    logger: P.Logger,
    sock: WhatsAppSocket | null,
    recipientJid: string,
    text: string
  ): Promise<proto.WebMessageInfo | void> {
    if (!sock || !sock.user) {
      logger.error(
        "Cannot send message: WhatsApp socket not connected or initialized."
      );
      return;
    }
    if (!recipientJid) {
      logger.error("Cannot send message: Recipient JID is missing.");
      return;
    }
    if (!text) {
      logger.error("Cannot send message: Message text is empty.");
      return;
    }
  
    try {
      logger.info(
        `Sending message to ${recipientJid}: ${text.substring(0, 50)}...`
      );
      const normalizedJid = jidNormalizedUser(recipientJid);
      const result = await sock.sendMessage(normalizedJid, { text: text });
      logger.info({ msgId: result?.key.id }, "Message sent successfully");
      return result;
    } catch (error) {
      logger.error({ err: error, recipientJid }, "Failed to send message");
      return;
    }
  }