Apple Notes MCP Server

Instructions

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 """