# Dan8Oren/mcp-apple-notes [Health: Active] **Category:** ๐Ÿข Workplace & Productivity **Repository:** https://github.com/Dan8Oren/mcp-apple-notes **GitHub Stars:** 12 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/dan8oren-mcp-apple-notes ## Description Semantic search and RAG over Apple Notes with on-device embeddings, full CRUD, folder management, and fuzzy title matching. 10 tools. Runs fully locally โ€” no API keys required. ## Tools Capabilities this server exposes over MCP: - **index-notes** โ€” Index all notes for semantic search. Run this first - **list-folders** โ€” List all Apple Notes folders with full paths and note counts - **list-notes** โ€” List notes with metadata. Optional `path` filter, `includeContent` flag, and `contentPreviewChars` (HTML-stripped per-note preview truncated to N chars โ€” one fast call, avoids the response token cap when listing many notes' content) - **search-notes** โ€” Semantic + full-text search with optional path filter and limit - **get-note** โ€” Get full content by noteId or title. Returns candidates on ambiguity - **create-note** โ€” Create a new note with markdown content, optionally in a folder - **edit-note** โ€” Edit title and/or content (markdown) of an existing note - **append-to-note** โ€” Append markdown content to an existing note - **move-note** โ€” Move a note to a different folder - **delete-note** โ€” Delete a note (moves to Recently Deleted) ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "mcp-apple-notes": { "command": "npx", "args": ["-y","If"], "env": { "MCP_APPLE_NOTES_READ_ONLY": "" } } } ``` **Requires environment variables:** `MCP_APPLE_NOTES_READ_ONLY` โ€” the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README

Features ยท Security ยท Installation ยท Tools ยท Verification ยท Response Shape

# MCP Apple Notes ![MCP Apple Notes](https://raw.githubusercontent.com/Dan8Oren/mcp-apple-notes/HEAD/images/logo.png) [![mcp-apple-notes MCP server](https://glama.ai/mcp/servers/Dan8Oren/mcp-apple-notes/badges/score.svg)](https://glama.ai/mcp/servers/Dan8Oren/mcp-apple-notes) A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables semantic search and RAG (Retrieval Augmented Generation) over your Apple Notes. Works with any MCP-compatible client โ€” Claude Desktop, Cursor, Windsurf, Cline, and others. ![MCP Apple Notes Demo](https://raw.githubusercontent.com/Dan8Oren/mcp-apple-notes/HEAD/images/demo.png) ## Features - ๐Ÿ” Semantic search over Apple Notes using [`all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) on-device embeddings model - ๐Ÿ“ Full-text search capabilities - ๐Ÿ“‚ Folder support โ€” list folders, browse by folder, filter search by folder - ๐Ÿ“Š Vector storage using [LanceDB](https://lancedb.github.io/lancedb/) - ๐Ÿค– Works with any MCP-compatible client (Claude, Cursor, Windsurf, Cline, etc.) - ๐ŸŽ Native Apple Notes integration via JXA - ๐Ÿ”’ Optional [read-only mode](#read-only-mode) for safe exploration - ๐Ÿƒโ€โ™‚๏ธ Fully local execution โ€” no API keys needed ## Security & Transparency Because this server interacts with your **private Apple Notes**, it is designed with absolute transparency in mind. It runs 100% locally on your Mac. - **No Cloud, No Telemetry** โ€” No API keys, no data leaving your machine. - **Native Apple JXA** โ€” Uses Apple's official [JavaScript for Automation](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/) scripting bridge. - **Embeddings on-device** โ€” The [`all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model runs locally via [`@huggingface/transformers`](https://github.com/huggingface/transformers.js). - **Verifiable** โ€” You are highly encouraged to read every line of code (especially [`index.ts`](https://github.com/Dan8Oren/mcp-apple-notes/blob/HEAD/index.ts)) before it ever touches your notes. - **GitHub releases** include SHA-256 checksums so you can verify downloaded artifacts. ## Installation & Setup Choose the installation method that fits your workflow. --- ### Method 1: Install from source (recommended) By cloning the repository locally, you can inspect the source code and know exactly what is executing on your machine. **Prerequisites:** [Node.js](https://nodejs.org) (v18+) or [Bun](https://bun.sh/docs/installation)
Using Bun? ```bash git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && bun install ``` ```json { "mcpServers": { "apple-notes": { "command": "bun", "args": ["run", "/path/to/mcp-apple-notes/index.ts"] } } } ```
### Using NPM: ```bash git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && npm install ``` Then add the server to your MCP client config. Replace `/path/to/mcp-apple-notes` with where you cloned the repo: ```json { "mcpServers": { "apple-notes": { "command": "npx", "args": ["tsx", "/path/to/mcp-apple-notes/index.ts"] } } } ``` > **Tip:** Want to try it without risk? Enable [read-only mode](#read-only-mode) to block all write operations while you explore. \ > `"env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }` --- ### Method 2: Quick start via npx If you prefer a **zero-setup** approach and trust the published npm package, you can simply add this directly to your MCP config: ```json { "mcpServers": { "apple-notes": { "command": "npx", "args": ["-y", "@dan8oren/mcp-apple-notes"] } } } ``` --- After setup, restart your client and ask your AI assistant to **"index my notes"** to get started. ### Per-client instructions
Claude Desktop 1. Open **Settings โ†’ Developer โ†’ Edit Config** 2. Paste your chosen JSON config into `claude_desktop_config.json` 3. Restart Claude Desktop Logs: ```bash tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log ```
Claude Code ```bash # npm version: claude mcp add apple-notes npx -- -y @dan8oren/mcp-apple-notes # or from source: claude mcp add apple-notes npx -- tsx /path/to/mcp-apple-notes/index.ts ```
Cursor Add the JSON config to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root.
Windsurf Add the JSON config to `~/.windsurf/mcp.json`.
## Available Tools | Tool | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `index-notes` | Index all notes for semantic search. Run this first | | `list-folders` | List all Apple Notes folders with full paths and note counts | | `list-notes` | List notes with metadata. Optional `path` filter, `includeContent` flag, and `contentPreviewChars` (HTML-stripped per-note preview truncated to N chars โ€” one fast call, avoids the response token cap when listing many notes' content) | | `search-notes` | Semantic + full-text search with optional path filter and limit | | `get-note` | Get full content by noteId or title. Returns candidates on ambiguity | | `create-note` | Create a new note with markdown content, optionally in a folder | | `edit-note` | Edit title and/or content (markdown) of an existing note | | `append-to-note` | Append markdown content to an existing note | | `move-note` | Move a note to a different folder | | `delete-note` | Delete a note (moves to Recently Deleted) | ## Verify Before You Trust Every Apple Notes operation is a [JXA](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/) call you can inspect in [`index.ts`](https://github.com/Dan8Oren/mcp-apple-notes/blob/HEAD/index.ts). No network requests, no background syncing โ€” just local scripting bridge calls. ### Read-only mode Want a safety net? Enable read-only mode to block all write operations โ€” only search, list, and read tools will be available: ```json { "mcpServers": { "apple-notes": { "command": "npx", "args": ["-y", "@dan8oren/mcp-apple-notes"], "env": { "MCP_APPLE_NOTES_READ_ONLY": "1" } } } } ``` When enabled, only these tools are available: `index-notes`, `list-folders`, `list-notes`, `search-notes`, `get-note`. ### Verbose mode Enable verbose logging to see every JXA call before it executes (logged to stderr): **CLI flag** โ€” add `--verbose` to your MCP client config args: ```json { "mcpServers": { "apple-notes": { "command": "npx", "args": ["--verbose", "-y", "@dan8oren/mcp-apple-notes"] } } } ``` **Environment variable** โ€” for clients that support `env`: ```json { "mcpServers": { "apple-notes": { "command": "npx", "args": ["-y", "@dan8oren/mcp-apple-notes"], "env": { "MCP_APPLE_NOTES_VERBOSE": "1" } } } } ``` ### JXA operations reference | Operation | Type | What it does | | -------------------- | ----------- | -------------------------------------------- | | `getNotes` | Read | Lists all notes (id, title, folder path) | | `getFolders` | Read | Lists all folders with paths and note counts | | `getNotesByPath` | Read | Gets notes in a specific folder | | `getNoteDetailsById` | Read | Gets full content of one note by ID | | `createNote` | Write | Creates a new note with title and content | | `appendToNote` | Write | Appends HTML content to an existing note | | `editNote` | Write | Updates title and/or content of a note | | `moveNote` | Write | Moves a note to a different folder | | `deleteNote` | Destructive | Moves a note to Recently Deleted | All operations go through Apple's JXA scripting bridge (`Application('Notes')`). No direct file system access, no network calls. The `delete` operation is non-permanent โ€” notes go to Recently Deleted and can be recovered within 30 days. ## Response Shape Tool responses are JSON objects in a consistent envelope: - Success: `{ "ok": true, "data": ... }` - Error: `{ "ok": false, "error": { "type": "...", "message": "..." } }` Most note-oriented responses now include the stable Apple Notes `id` so clients can track notes safely across renames and moves. ## Community & Support Bug reports, ideas, questions, and showcases all have a home โ€” please use the channel that fits: - ๐Ÿ› **Found a bug?** โ†’ [Open an issue](https://github.com/Dan8Oren/mcp-apple-notes/issues/new/choose) - ๐Ÿ’ก **Have a feature idea?** โ†’ [Start a thread in Ideas](https://github.com/Dan8Oren/mcp-apple-notes/discussions/categories/ideas) - โ“ **Need help with setup or integration?** โ†’ [Ask in Q&A](https://github.com/Dan8Oren/mcp-apple-notes/discussions/categories/q-a) - ๐Ÿ›  **Built something cool with it?** โ†’ [Share in Show and tell](https://github.com/Dan8Oren/mcp-apple-notes/discussions/categories/show-and-tell) - ๐Ÿ“ฃ **Watch for updates** โ†’ [Announcements](https://github.com/Dan8Oren/mcp-apple-notes/discussions/categories/announcements) PRs are welcome. For non-trivial changes, please open an issue or discussion first so we can align on direction before you invest time. ## Acknowledgments Originally based on [RafalWilinski/mcp-apple-notes](https://github.com/RafalWilinski/mcp-apple-notes).