Apple Notes MCP Server

Instructions

Implementation Reference

• apple_notes.py:129-195 (handler)

  The main handler function for the 'search_notes' tool. It uses AppleScript via osascript to search notes by content or name in a specified account or all accounts, parses the results, and returns a formatted list of matching notes.
  @mcp.tool() async def search_notes(query: str, account: Optional[str] = None) -> str: """Search for notes containing the specified text. Args: query: Text to search for in note content account: Optional account name to search within """ if account: script = f''' tell application "Notes" set accountName to "{escape_applescript_string(account)}" set searchResults to {{}} try set targetAccount to account accountName repeat with aNote in notes of targetAccount set noteContent to body of aNote if noteContent contains "{escape_applescript_string(query)}" or name of aNote contains "{escape_applescript_string(query)}" then set end of searchResults to (name of aNote) & "|" & (id of aNote) end if end repeat end try return searchResults end tell ''' else: script = f''' tell application "Notes" set searchResults to {{}} repeat with anAccount in accounts repeat with aNote in notes of anAccount set noteContent to body of aNote if noteContent contains "{escape_applescript_string(query)}" or name of aNote contains "{escape_applescript_string(query)}" then set end of searchResults to (name of anAccount) & "::" & (name of aNote) & "|" & (id of aNote) end if end repeat end repeat return searchResults end tell ''' output, success = run_applescript(script) if not success: return output if not output or output == "{}": return f"No notes found containing '{query}'." results = [] for item in output.split(", "): item = item.strip().strip('"').strip("'") if "|" in item: parts = item.split("|") if len(parts) >= 2: results.append({ "name": parts[0], "id": parts[1] }) if not results: return f"No notes found containing '{query}'." result = f"Found {len(results)} note(s) containing '{query}':\n" for i, note in enumerate(results, 1): result += f"{i}. {note['name']} (ID: {note['id']})\n" return result
• apple_notes.py:17-34 (helper)

  Helper function used by search_notes to execute AppleScript commands and handle subprocess output and errors.
  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-43 (helper)

  Helper function used by search_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:129-129 (registration)

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