notes
Search, retrieve, and create notes in the Apple Notes app. Use this tool to organize notes, find specific content, and manage folders through the Apple MCP Server.
Instructions
Search, retrieve and create notes in Apple Notes app
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Content of the note to create (required for create operation) | |
| folderName | No | Name of the folder to create the note in (optional for create operation, defaults to 'Claude') | |
| operation | Yes | Operation to perform: 'search', 'list', or 'create' | |
| searchText | No | Text to search for in notes (required for search operation) | |
| title | No | Title of the note to create (required for create operation) |
Input Schema (JSON Schema)
{
"properties": {
"body": {
"description": "Content of the note to create (required for create operation)",
"type": "string"
},
"folderName": {
"description": "Name of the folder to create the note in (optional for create operation, defaults to 'Claude')",
"type": "string"
},
"operation": {
"description": "Operation to perform: 'search', 'list', or 'create'",
"enum": [
"search",
"list",
"create"
],
"type": "string"
},
"searchText": {
"description": "Text to search for in notes (required for search operation)",
"type": "string"
},
"title": {
"description": "Title of the note to create (required for create operation)",
"type": "string"
}
},
"required": [
"operation"
],
"type": "object"
}
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; }