send_imessage

Instructions

Implementation Reference

• src/imessage_mcp/server.py:13-24 (registration)

  The tool 'send_imessage' is registered as an MCP tool via @mcp.tool() decorator. It validates service param then delegates to the send module.

  @mcp.tool()
  def send_imessage(recipient: str, body: str, service: str = "iMessage") -> dict[str, Any]:
      """Send an iMessage/SMS via Messages.app.
  
      Args:
          recipient: phone (+15551234567), Apple ID email, or an existing buddy name.
          body: message text.
          service: "iMessage" (default) or "SMS".
      """
      if service not in ("iMessage", "SMS"):
          raise ValueError("service must be 'iMessage' or 'SMS'")
      return send.send_imessage(recipient=recipient, body=body, service=service)  # type: ignore[arg-type]

• src/imessage_mcp/send.py:37-73 (handler)

  Core implementation of send_imessage. Validates inputs, invokes AppleScript via osascript subprocess to send the message through Messages.app, and returns status.

  def send_imessage(recipient: str, body: str, service: Service = "iMessage") -> dict:
      if not recipient or not recipient.strip():
          raise SendError("recipient is required")
      if body is None:
          raise SendError("body is required")
      if service not in ("iMessage", "SMS"):
          raise SendError("service must be 'iMessage' or 'SMS'")
  
      try:
          result = subprocess.run(
              ["osascript", "-e", APPLESCRIPT, recipient, body, service],
              capture_output=True,
              text=True,
              timeout=20,
          )
      except FileNotFoundError as exc:
          raise SendError("osascript not found — is this macOS?") from exc
      except subprocess.TimeoutExpired as exc:
          raise SendError("osascript timed out after 20s") from exc
  
      if result.returncode != 0:
          stderr = (result.stderr or "").strip()
          hint = ""
          lower = stderr.lower()
          if "not authorized" in lower or "1743" in stderr or "-1743" in stderr:
              hint = (
                  " — grant automation permission at: System Settings → Privacy & "
                  "Security → Automation → your terminal/Claude → enable 'Messages'."
              )
          raise SendError(f"send failed (exit {result.returncode}): {stderr}{hint}")
  
      return {
          "status": "sent",
          "recipient": recipient,
          "service": service,
          "body_preview": body[:120],
      }

• src/imessage_mcp/server.py:22-24 (helper)

  Delegation call from the tool registration to the actual send handler module.

  if service not in ("iMessage", "SMS"):
      raise ValueError("service must be 'iMessage' or 'SMS'")
  return send.send_imessage(recipient=recipient, body=body, service=service)  # type: ignore[arg-type]

• src/imessage_mcp/send.py:18-34 (helper)

  The AppleScript string used by the handler to interface with macOS Messages.app.

  APPLESCRIPT = r'''
  on run argv
      set theRecipient to item 1 of argv
      set theBody to item 2 of argv
      set theService to item 3 of argv
      tell application "Messages"
          if theService is "SMS" then
              set svc to 1st service whose service type = SMS
          else
              set svc to 1st service whose service type = iMessage
          end if
          set theBuddy to buddy theRecipient of svc
          send theBody to theBuddy
      end tell
      return "sent"
  end run
  '''

• src/imessage_mcp/send.py:12-12 (schema)

  Literal type alias 'Service' defining valid service values ('iMessage' | 'SMS').

  Service = Literal["iMessage", "SMS"]