Apple MCP Server

Instructions

Implementation Reference

• index.ts:276-367 (handler)

  Main execution handler for the 'notes' tool. Dispatches to search, list, or create operations using helper functions from utils/notes.ts.

  case "notes": {
  	if (!isNotesArgs(args)) {
  		throw new Error("Invalid arguments for notes tool");
  	}
  
  	try {
  		const notesModule = await loadModule("notes");
  		const { operation } = args;
  
  		switch (operation) {
  			case "search": {
  				if (!args.searchText) {
  					throw new Error(
  						"Search text is required for search operation",
  					);
  				}
  
  				const foundNotes = await notesModule.findNote(args.searchText);
  				return {
  					content: [
  						{
  							type: "text",
  							text: foundNotes.length
  								? foundNotes
  										.map((note) => `${note.name}:\n${note.content}`)
  										.join("\n\n")
  								: `No notes found for "${args.searchText}"`,
  						},
  					],
  					isError: false,
  				};
  			}
  
  			case "list": {
  				const allNotes = await notesModule.getAllNotes();
  				return {
  					content: [
  						{
  							type: "text",
  							text: allNotes.length
  								? allNotes
  										.map((note) => `${note.name}:\n${note.content}`)
  										.join("\n\n")
  								: "No notes exist.",
  						},
  					],
  					isError: false,
  				};
  			}
  
  			case "create": {
  				if (!args.title || !args.body) {
  					throw new Error(
  						"Title and body are required for create operation",
  					);
  				}
  
  				const result = await notesModule.createNote(
  					args.title,
  					args.body,
  					args.folderName,
  				);
  
  				return {
  					content: [
  						{
  							type: "text",
  							text: result.success
  								? `Created note "${args.title}" in folder "${result.folderName}"${result.usedDefaultFolder ? " (created new folder)" : ""}.`
  								: `Failed to create note: ${result.message}`,
  						},
  					],
  					isError: !result.success,
  				};
  			}
  
  			default:
  				throw new Error(`Unknown operation: ${operation}`);
  		}
  	} catch (error) {
  		const errorMessage = error instanceof Error ? error.message : String(error);
  		return {
  			content: [
  				{
  					type: "text",
  					text: errorMessage.includes("access") ? errorMessage : `Error accessing notes: ${errorMessage}`,
  				},
  			],
  			isError: true,
  		};
  	}
  }

• tools.ts:17-47 (schema)

  Input schema and metadata definition for the 'notes' tool.

  const NOTES_TOOL: Tool = {
    name: "notes", 
    description: "Search, retrieve and create notes in Apple Notes app",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          description: "Operation to perform: 'search', 'list', or 'create'",
          enum: ["search", "list", "create"]
        },
        searchText: {
          type: "string",
          description: "Text to search for in notes (required for search operation)"
        },
        title: {
          type: "string",
          description: "Title of the note to create (required for create operation)"
        },
        body: {
          type: "string",
          description: "Content of the note to create (required for create operation)"
        },
        folderName: {
          type: "string",
          description: "Name of the folder to create the note in (optional for create operation, defaults to 'Claude')"
        }
      },
      required: ["operation"]
    }
  };

• tools.ts:294-296 (registration)

  The 'notes' tool (NOTES_TOOL) is registered in the exported tools array used by the MCP server for tool listing.

  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, CALENDAR_TOOL, MAPS_TOOL];
  
  export default tools;

• utils/notes.ts:493-501 (helper)

  Helper functions exported from utils/notes.ts, including getAllNotes, findNote, and createNote, which implement the core logic for interacting with Apple Notes app via AppleScript.

  export default {
  	getAllNotes,
  	findNote,
  	createNote,
  	getNotesFromFolder,
  	getRecentNotesFromFolder,
  	getNotesByDateRange,
  	requestNotesAccess,
  };

• index.ts:1338-1383 (schema)

  Runtime type validation function for notes tool arguments, complementing the JSON schema.

  function isNotesArgs(args: unknown): args is {
  	operation: "search" | "list" | "create";
  	searchText?: string;
  	title?: string;
  	body?: string;
  	folderName?: string;
  } {
  	if (typeof args !== "object" || args === null) {
  		return false;
  	}
  
  	const { operation } = args as { operation?: unknown };
  	if (typeof operation !== "string") {
  		return false;
  	}
  
  	if (!["search", "list", "create"].includes(operation)) {
  		return false;
  	}
  
  	// Validate fields based on operation
  	if (operation === "search") {
  		const { searchText } = args as { searchText?: unknown };
  		if (typeof searchText !== "string" || searchText === "") {
  			return false;
  		}
  	}
  
  	if (operation === "create") {
  		const { title, body } = args as { title?: unknown; body?: unknown };
  		if (typeof title !== "string" || title === "" || typeof body !== "string") {
  			return false;
  		}
  
  		// Check folderName if provided
  		const { folderName } = args as { folderName?: unknown };
  		if (
  			folderName !== undefined &&
  			(typeof folderName !== "string" || folderName === "")
  		) {
  			return false;
  		}
  	}
  
  	return true;
  }