Apple Notes MCP Server

Implementation Reference

• src/index.ts:67-93 (registration)

  Registration of the 'search-notes' MCP tool, including the inline handler function that executes the tool logic by calling notesManager.searchNotes and formatting the response.

  server.tool(
    "search-notes",
    searchSchema,
    async ({ query }: SearchParams) => {
      try {
        const notes = notesManager.searchNotes(query);
        const message = notes.length
          ? `Found ${notes.length} notes:\n${notes.map(note => `• ${note.title}`).join('\n')}`
          : "No notes found matching your query";
  
        return {
          content: [{
            type: "text",
            text: message
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error searching notes: ${error instanceof Error ? error.message : 'Unknown error'}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:24-26 (schema)

  Input schema definition for the 'search-notes' tool using Zod validation.

  const searchSchema = {
    query: z.string().min(1, "Search query is required")
  };

• src/types.ts:23-25 (schema)

  TypeScript interface for SearchParams used in the tool handler signature.

  export interface SearchParams {
    query: string;
  }

• src/services/appleNotesManager.ts:61-93 (helper)

  Core implementation of note searching in AppleNotesManager using AppleScript to query Notes.app for notes matching the query in title.

  /**
   * Searches for notes by title
   * @param query - The search query
   * @returns Array of matching notes
   */
  searchNotes(query: string): Note[] {
    const sanitizedQuery = query.replace(/"/g, '\\"');
    const script = `
      tell application "Notes"
        tell account "${this.ICLOUD_ACCOUNT}"
          get name of notes where name contains "${sanitizedQuery}"
        end tell
      end tell
    `;
  
    const result = runAppleScript(script);
    if (!result.success) {
      console.error('Failed to search notes:', result.error);
      return [];
    }
  
    return result.output
      .split(',')
      .filter(Boolean)
      .map(title => ({
        id: Date.now().toString(),
        title: title.trim(),
        content: '',
        tags: [],
        created: new Date(),
        modified: new Date()
      }));
  }

• src/utils/applescript.ts:9-35 (helper)

  Utility function to execute AppleScript commands, used by searchNotes to interact with Apple Notes.app.

  export function runAppleScript(script: string): AppleScriptResult {
    try {
      // Trim and sanitize the script
      const sanitizedScript = script.trim().replace(/[\r\n]+/g, ' ');
  
      // Execute the AppleScript command
      const output = execSync(`osascript -e '${sanitizedScript}'`, {
        encoding: 'utf8',
        timeout: 10000 // 10 second timeout
      });
  
      return {
        success: true,
        output: output.trim()
      };
    } catch (error) {
      console.error('AppleScript execution failed:', error);
  
      return {
        success: false,
        output: '',
        error: error instanceof Error
          ? error.message
          : 'Unknown error occurred while executing AppleScript'
      };
    }
  }