Dan8Oren/mcp-apple-notes

MCP Apple Notes
A Model Context Protocol (MCP) 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.
Features
- 🔍 Semantic search over Apple Notes using 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
- 🤖 Works with any MCP-compatible client (Claude, Cursor, Windsurf, Cline, etc.)
- 🍎 Native Apple Notes integration via JXA
- 🔒 Optional 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 scripting bridge.
- **Embeddings on-device** — The all-MiniLM-L6-v2 model runs locally via @huggingface/transformers.
- **Verifiable** — You are highly encouraged to read every line of code (especially 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 (v18+) or Bun
Using Bun?
Using NPM:
Then add the server to your MCP client config. Replace /path/to/mcp-apple-notes with where you cloned the repo:
> **Tip:** Want to try it without risk? Enable 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:
---
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:
Claude Code
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) |