macOS MCP Servers

Instructions

Implementation Reference

• src/notes/index.ts:192-230 (handler)

  The handler function for the 'list_notes' tool. It constructs and executes an AppleScript via runAppleScript to list up to the first 20 notes from the Apple Notes app, formats the result, and returns it as text content.

  case 'list_notes': {
    const script = `
      tell application "Notes"
        set noteList to {}
        set noteCount to count of notes
        if noteCount > 0 then
          repeat with i from 1 to noteCount
            if i > 20 then exit repeat
            try
              set aNote to note i
              set noteTitle to name of aNote
              set end of noteList to noteTitle
            on error
              set end of noteList to "Note " & i & " (error reading)"
            end try
          end repeat
        end if
        
        if length of noteList = 0 then
          return "No notes found"
        else
          set AppleScript's text item delimiters to "\\n"
          set noteString to noteList as string
          set AppleScript's text item delimiters to ""
          return "Found " & (length of noteList) & " notes:\\n" & noteString
        end if
      end tell
    `;
    
    const result = await runAppleScript(script);
    return {
      content: [
        {
          type: 'text',
          text: `Notes:\\n${result}`,
        },
      ],
    };
  }

• src/notes/index.ts:73-79 (registration)

  Registers the 'list_notes' tool in the MCP server's tool list, including its name, description, and empty input schema.

    name: 'list_notes',
    description: 'Get a list of all notes',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/notes/index.ts:28-43 (helper)

  Helper function used by the list_notes handler (and others) to execute AppleScript code safely by writing to a temp file and running via osascript.

  async function runAppleScript(script: string): Promise<string> {
    try {
      // Write script to temporary file to avoid shell escaping issues
      const tempFile = join(tmpdir(), `applescript-${Date.now()}.scpt`);
      writeFileSync(tempFile, script, 'utf8');
      
      try {
        const { stdout } = await execAsync(`osascript "${tempFile}"`);
        return stdout.trim();
      } finally {
        unlinkSync(tempFile);
      }
    } catch (error: any) {
      throw new McpError(ErrorCode.InternalError, `AppleScript error: ${error.message}`);
    }
  }