Apple Notes MCP Server

Instructions

Args:
    account: Optional account name (e.g., "iCloud", "On My Mac")
    folder: Optional folder name within the account

Implementation Reference

• apple_notes.py:46-126 (handler)

  The handler function decorated with @mcp.tool() that implements the list_notes tool. It generates AppleScript based on optional account and folder parameters, executes it using run_applescript, parses the output, and formats a list of notes with names, IDs, and modification dates.

  @mcp.tool()
  async def list_notes(account: Optional[str] = None, folder: Optional[str] = None) -> str:
      """List all notes or notes from a specific account/folder.
      
      Args:
          account: Optional account name (e.g., "iCloud", "On My Mac")
          folder: Optional folder name within the account
      """
      if account and folder:
          script = f'''
          tell application "Notes"
              set accountName to "{escape_applescript_string(account)}"
              set folderName to "{escape_applescript_string(folder)}"
              set noteList to {{}}
              try
                  set targetAccount to account accountName
                  set targetFolder to folder folderName of targetAccount
                  repeat with aNote in notes of targetFolder
                      set end of noteList to (name of aNote) & "|" & (id of aNote) & "|" & (modification date of aNote as string)
                  end repeat
              end try
              return noteList
          end tell
          '''
      elif account:
          script = f'''
          tell application "Notes"
              set accountName to "{escape_applescript_string(account)}"
              set noteList to {{}}
              try
                  set targetAccount to account accountName
                  repeat with aNote in notes of targetAccount
                      set end of noteList to (name of aNote) & "|" & (id of aNote) & "|" & (modification date of aNote as string)
                  end repeat
              end try
              return noteList
          end tell
          '''
      else:
          script = '''
          tell application "Notes"
              set noteList to {}
              repeat with anAccount in accounts
                  repeat with aNote in notes of anAccount
                      set end of noteList to (name of anAccount) & "::" & (name of aNote) & "|" & (id of aNote) & "|" & (modification date of aNote as string)
                  end repeat
              end repeat
              return noteList
          end tell
          '''
      
      output, success = run_applescript(script)
      if not success:
          return output
      
      # Parse the output
      if not output or output == "{}":
          return "No notes found."
      
      # AppleScript returns a list like: {"Note 1|id1|date1", "Note 2|id2|date2"}
      # Parse it
      notes = []
      for item in output.split(", "):
          item = item.strip().strip('"').strip("'")
          if "|" in item:
              parts = item.split("|")
              if len(parts) >= 3:
                  notes.append({
                      "name": parts[0],
                      "id": parts[1],
                      "modified": parts[2]
                  })
      
      if not notes:
          return "No notes found."
      
      result = "Found notes:\n"
      for i, note in enumerate(notes, 1):
          result += f"{i}. {note['name']} (ID: {note['id']}, Modified: {note['modified']})\n"
      
      return result

• apple_notes.py:17-35 (helper)

  Helper function used by list_notes to execute AppleScript commands via subprocess and return output or error.

  def run_applescript(script: str) -> tuple[str, bool]:
      """Run an AppleScript command and return the output."""
      try:
          result = subprocess.run(
              ["osascript", "-e", script],
              capture_output=True,
              text=True,
              timeout=30
          )
          if result.returncode == 0:
              return result.stdout.strip(), True
          else:
              error_msg = result.stderr.strip() or result.stdout.strip()
              return f"Error: {error_msg}", False
      except subprocess.TimeoutExpired:
          return "Error: AppleScript execution timed out", False
      except Exception as e:
          return f"Error: {str(e)}", False

• apple_notes.py:37-44 (helper)

  Helper function used by list_notes to properly escape strings for safe inclusion in AppleScript.

  def escape_applescript_string(text: str) -> str:
      """Escape special characters for AppleScript strings."""
      # Replace backslashes, quotes, and newlines
      text = text.replace("\\", "\\\\")
      text = text.replace('"', '\\"')
      text = text.replace("\n", "\\n")
      return text

• apple_notes.py:46-46 (registration)

  The @mcp.tool() decorator registers the list_notes function as an MCP tool.

  @mcp.tool()

• apple_notes.py:48-53 (schema)

  Docstring defining the input schema (parameters) for the list_notes tool.

  """List all notes or notes from a specific account/folder.
  
  Args:
      account: Optional account name (e.g., "iCloud", "On My Mac")
      folder: Optional folder name within the account
  """