Apple Notes MCP Server

What is Apple Notes MCP Server?

Apple Notes MCP Server (mcp-apple-notes by RafalWilinski) is a local apple notes mcp server that lets Claude search, read and create your Apple Notes, with semantic search and RAG powered by an on-device embeddings model.

It is a community, open-source project, not an Apple product. It reads notes from the Notes app through JXA (JavaScript for Automation), embeds them with the all-MiniLM-L6-v2 model and stores the vectors in LanceDB on your Mac. No API keys or cloud services are involved, so you can ask questions about your notes in plain language and Claude finds the relevant ones. Note that the repository has not been updated since December 2024, and several open issues report setup problems (see Troubleshooting).

How to use Apple Notes MCP Server?

Prerequisites: a Mac with the Apple Notes app, Bun and an MCP client such as Claude Desktop.

Clone the repository and install dependencies:

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

Claude Desktop

1. Open Claude Desktop and go to Settings → Developer → Edit Config.
2. Add an entry to claude_desktop_config.json that runs index.ts with Bun:

{
  "mcpServers": {
    "apple-notes": {
      "command": "/Users/<YOUR_USER_NAME>/.bun/bin/bun",
      "args": ["/Users/<YOUR_USER_NAME>/mcp-apple-notes/index.ts"]
    }
  }
}

Replace <YOUR_USER_NAME> with your macOS username and make sure the path matches where you cloned the repo. The README example uses apple-notes-mcp as the folder name, but git clone creates mcp-apple-notes; open issues on the repo point out this mismatch.

3. Restart Claude Desktop and check that the server shows as connected.
4. Ask Claude to "Index my notes" or "Index my Apple Notes" before searching. Indexing can take from a few seconds to a few minutes depending on how many notes you have.

Claude Code

The README only documents Claude Desktop. Claude Code can run the same stdio command:

claude mcp add apple-notes -- /Users/<YOUR_USER_NAME>/.bun/bin/bun /Users/<YOUR_USER_NAME>/mcp-apple-notes/index.ts

Other MCP clients such as Cursor can use the same command and args in their mcpServers config. macOS may ask you to allow the app that launches the server to control Notes.

Key features of Apple Notes MCP Server

• Semantic search over Apple Notes using the on-device all-MiniLM-L6-v2 embeddings model.
• Full-text search alongside vector search.
• Local vector storage with LanceDB.
• Native Apple Notes access through JXA, with no export step.
• Note creation from Claude (the create-note tool).
• Fully local execution with no API keys.
• Small TypeScript codebase that runs directly with Bun.

Apple Notes MCP Server tools

The server registers five tools in index.ts:

• Indexing: index-notes reads every note and builds the semantic search index. Run it first and again after you add many notes.
• Finding notes: search-notes searches by title or content using the index; list-notes returns just the titles of all notes.
• Reading: get-note returns a note's full content and details by title.
• Writing: create-note creates a new note from a title and content. The tool expects HTML content without newlines.

Use cases of Apple Notes MCP Server

• Recall: "What did I write about the Q3 offsite?" answered from your own notes.
• Find old snippets: "Find the note where I saved the router setup steps."
• Summarize a topic: "Summarize everything in my notes about the kitchen renovation."
• Personal knowledge base for RAG: let Claude ground answers in your notes instead of general knowledge.
• Capture from chat: "Save this meeting summary as a new note called 'Weekly sync'."

Apple Notes MCP Server vs alternatives

• Other apple notes mcp server projects: several community servers drive Notes.app with AppleScript and add folder support or edit and delete operations. Forks of this repository also exist, for example Dan8Oren/mcp-apple-notes (folder support and bug fixes) and connerkward/mcp-apple-notes, which reads the Notes database directly instead of using JXA. Check their maintenance status before choosing one.
• Obsidian MCP Server: a better fit if your notes live in Markdown files in an Obsidian vault rather than in Apple Notes.
• Notion MCP Server (Official): for notes and docs kept in Notion, with a vendor-maintained server.

Troubleshooting Apple Notes MCP Server

• Server does not start: check that the args path points to the real location of index.ts (the clone folder is mcp-apple-notes) and that command points to your Bun binary (~/.bun/bin/bun).
• Find the logs: run tail -n 50 -f ~/Library/Logs/Claude/mcp.log, or the server-specific mcp-server-<name>.log in the same folder.
• Indexing times out: an open issue reports that index-notes on a large library can take longer than Claude Desktop's request timeout. Community forks report much faster indexing if this keeps happening.
• JXA errors: some users report that the run-jxa dependency fails on recent macOS versions. Make sure the launching app is allowed to automate Notes in System Settings, and consider a maintained fork if the errors persist.
• Search misses recent notes: run "index my notes" again so new notes are embedded.