WhatsApp MCP Server

Instructions

Implementation Reference

• src/index.ts:65-139 (handler)

  The async handler function that receives contactName and message, formats the message, constructs AppleScript for UI automation to send the WhatsApp message, executes it via runAppleScript, and returns success or error content.

  async ({ contactName, message }) => {
    try {
      // Format the message for proper line breaks
      const formattedMessage = formatWhatsAppMessage(message);
  
      // Optimized AppleScript with minimal delays
      const appleScript = `
        tell application "WhatsApp" to activate
        delay 1 -- Reduced from 4 to 1
        
        tell application "System Events"
          tell process "WhatsApp"
            -- Access the search field
            try
              -- Keyboard shortcut for search
              keystroke "f" using {command down}
              delay 0.5 -- Reduced from 2 to 0.5
              
              -- Clear any existing text
              keystroke "a" using {command down}
              keystroke (ASCII character 8) -- Backspace
              delay 0.5 -- Reduced from 1.5 to 0.5
              
              -- Type the contact name
              keystroke "${contactName.replace(/"/g, '\\"')}"
              
              -- Give time for search results to populate
              delay 1.5 -- Reduced from 6 to 1.5
              
              -- Contact selection method
              keystroke (ASCII character 31) -- first down arrow
              delay 0.3 -- Reduced from 1 to 0.3
              keystroke (ASCII character 31) -- second down arrow
              delay 0.3 -- Reduced from 1 to 0.3
              keystroke return -- press enter
              delay 0.8 -- Reduced from 3 to 0.8
              
              -- Type and send the message
              keystroke "${formattedMessage}"
              delay 0.5 -- Reduced from 2 to 0.5
              
              -- Send the message
              keystroke return
              delay 0.3 -- Reduced from 1 to 0.3
              
              return "Message sent using optimized timing"
            on error errMsg
              return "Failed to send message: " & errMsg
            end try
          end tell
        end tell
      `;
  
      const result = await runAppleScript(appleScript);
  
      return {
        content: [
          {
            type: "text",
            text: `Message sent to ${contactName}: "${message}"`,
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error sending message: ${error}`,
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:62-64 (schema)

  Zod schema for input parameters: contactName (string, full name as in WhatsApp) and message (string).

    contactName: z.string().describe("Full name of the contact as it appears in WhatsApp"),
    message: z.string().describe("Message content to send"),
  },

• src/index.ts:58-140 (registration)

  Registration of the 'send-whatsapp-message' tool on the MCP server, providing name, description, input schema, and handler function.

  server.tool(
    "send-whatsapp-message",
    "Send a message to a contact on WhatsApp",
    {
      contactName: z.string().describe("Full name of the contact as it appears in WhatsApp"),
      message: z.string().describe("Message content to send"),
    },
    async ({ contactName, message }) => {
      try {
        // Format the message for proper line breaks
        const formattedMessage = formatWhatsAppMessage(message);
  
        // Optimized AppleScript with minimal delays
        const appleScript = `
          tell application "WhatsApp" to activate
          delay 1 -- Reduced from 4 to 1
          
          tell application "System Events"
            tell process "WhatsApp"
              -- Access the search field
              try
                -- Keyboard shortcut for search
                keystroke "f" using {command down}
                delay 0.5 -- Reduced from 2 to 0.5
                
                -- Clear any existing text
                keystroke "a" using {command down}
                keystroke (ASCII character 8) -- Backspace
                delay 0.5 -- Reduced from 1.5 to 0.5
                
                -- Type the contact name
                keystroke "${contactName.replace(/"/g, '\\"')}"
                
                -- Give time for search results to populate
                delay 1.5 -- Reduced from 6 to 1.5
                
                -- Contact selection method
                keystroke (ASCII character 31) -- first down arrow
                delay 0.3 -- Reduced from 1 to 0.3
                keystroke (ASCII character 31) -- second down arrow
                delay 0.3 -- Reduced from 1 to 0.3
                keystroke return -- press enter
                delay 0.8 -- Reduced from 3 to 0.8
                
                -- Type and send the message
                keystroke "${formattedMessage}"
                delay 0.5 -- Reduced from 2 to 0.5
                
                -- Send the message
                keystroke return
                delay 0.3 -- Reduced from 1 to 0.3
                
                return "Message sent using optimized timing"
              on error errMsg
                return "Failed to send message: " & errMsg
              end try
            end tell
          end tell
        `;
  
        const result = await runAppleScript(appleScript);
  
        return {
          content: [
            {
              type: "text",
              text: `Message sent to ${contactName}: "${message}"`,
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error sending message: ${error}`,
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:38-46 (helper)

  Helper function runAppleScript that promisified exec of osascript to run AppleScript.

  async function runAppleScript(script: string) {
    try {
      const { stdout } = await execPromise(`osascript -e '${script.replace(/'/g, "'\\''")}'`);
      return stdout.trim();
    } catch (error) {
      console.error("AppleScript execution error:", error);
      throw new Error(`Failed to execute AppleScript: ${error}`);
    }
  }

• src/index.ts:49-55 (helper)

  Helper function formatWhatsAppMessage that replaces newlines and quotes for AppleScript compatibility.

  function formatWhatsAppMessage(message: string) {
    // Replace normal line breaks with AppleScript line breaks
    // This ensures proper line breaking in WhatsApp
    return message
      .replace(/\n/g, '" & return & "')
      .replace(/"/g, '\\"');
  }