mac-messages-mcp

Instructions

Check if a recipient has iMessage available.

This tool helps determine whether to send via iMessage or SMS/RCS.
Useful for debugging delivery issues or choosing the right service.

Args:
    recipient: Phone number or email to check for iMessage availability

Implementation Reference

• mac_messages_mcp/server.py:192-218 (handler)

  The MCP tool handler decorated with @mcp.tool(). It receives the recipient parameter, calls the helper _check_imessage_availability, and returns a formatted string indicating iMessage availability with emojis and explanations.

  @mcp.tool()
  def tool_check_imessage_availability(ctx: Context, recipient: str) -> str:
      """
      Check if a recipient has iMessage available.
      
      This tool helps determine whether to send via iMessage or SMS/RCS.
      Useful for debugging delivery issues or choosing the right service.
      
      Args:
          recipient: Phone number or email to check for iMessage availability
      """
      logger.info(f"Checking iMessage availability for: {recipient}")
      try:
          recipient = str(recipient)
          has_imessage = _check_imessage_availability(recipient)
          
          if has_imessage:
              return f"✅ {recipient} has iMessage available - messages will be sent via iMessage"
          else:
              # Check if it looks like a phone number for SMS fallback
              if any(c.isdigit() for c in recipient):
                  return f"📱 {recipient} does not have iMessage - messages will automatically fall back to SMS/RCS"
              else:
                  return f"❌ {recipient} does not have iMessage and SMS is not available for email addresses"
      except Exception as e:
          logger.error(f"Error checking iMessage availability: {str(e)}")
          return f"Error checking iMessage availability: {str(e)}"

• mac_messages_mcp/messages.py:950-985 (helper)

  The core helper function that executes AppleScript to query the Messages app for whether a buddy (recipient) exists in the iMessage service, returning a boolean.

  def _check_imessage_availability(recipient: str) -> bool:
      """
      Check if recipient has iMessage available.
      
      Args:
          recipient: Phone number or email to check
          
      Returns:
          True if iMessage is available, False otherwise
      """
      safe_recipient = recipient.replace('"', '\\"')
      
      script = f'''
      tell application "Messages"
          try
              set targetService to 1st service whose service type = iMessage
              set targetBuddy to buddy "{safe_recipient}" of targetService
              
              -- Check if buddy exists and has iMessage capability
              if targetBuddy exists then
                  return "true"
              else
                  return "false"
              end if
          on error
              return "false"
          end try
      end tell
      '''
      
      try:
          result = run_applescript(script)
          return result.strip().lower() == "true"
      except:
          return False