mcp-apple-notes

<div align="center"> <h3> <a href="#features">Features</a> · <a href="#security--transparency">Security</a> · <a href="#installation--setup">Installation</a> · <a href="#available-tools">Tools</a> · <a href="#verify-before-you-trust">Verification</a> · <a href="#response-shape">Response Shape</a> </h3> </div>

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.

!MCP Apple Notes Demo

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

<details> <summary><strong>Using Bun?</strong></summary>

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"]
    }
  }
}

</details>

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

<details> <summary><strong>Claude Desktop</strong></summary>

1. Open Settings → Developer → Edit Config
2. Paste your chosen JSON config into claude_desktop_config.json
3. Restart Claude Desktop

Logs:

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

# 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

</details>

<details> <summary><strong>Cursor</strong></summary>

Add the JSON config to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root.

</details>

<details> <summary><strong>Windsurf</strong></summary>

Add the JSON config to ~/.windsurf/mcp.json.

</details>

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

| 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
• 💡 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.