mcp-apple-notes Server

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

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && bun install

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

Using NPM:

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:

{
  "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 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:

{
  "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

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log

# 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

Available Tools

Verify Before You Trust

Every Apple Notes operation is a JXA call you can inspect in 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:

{
  "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:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["--verbose", "-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

Environment variable — for clients that support env:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_VERBOSE": "1" }
    }
  }
}

JXA operations reference

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
• 💡 Have a feature idea? → Start a thread in Ideas
• ❓ Need help with setup or integration? → Ask in Q&A
• 🛠 Built something cool with it? → Share in Show and tell
• 📣 Watch for updates → 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.