Apple Notes MCP Server

Instructions

Args:
    query: Text to search for in note content
    account: Optional account name to search within

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()