Model Context Protocol for macOS Notes Integration

A server adhering to the Model Context Protocol (MCP) that unlocks semantic retrieval and Retrieval Augmented Generation (RAG) capabilities for your collection of Apple Notes. This integration enables intelligent assistants, such as Claude, to accurately search and cite entries from your notes during ongoing dialogue sessions.

Core Capabilities

🔍 Vectorized Lookups: Executes deep semantic search across Apple Notes utilizing the embedded all-MiniLM-L6-v2 model for on-device vector generation.
📝 Comprehensive Text Scanning: Includes traditional, exact full-text search functionality.
📊 Data Persistence: Employs LanceDB for robust vector database management.
🤖 AI Interoperability: Presents as an MCP-compliant service endpoint ready for integration with advanced AI entities.
🍎 Native macOS Hook: Accesses note archives directly via JavaScript for Automation (JXA) within the Apple ecosystem.
🏃‍♂️ Zero External Dependencies: Operates completely within the local machine environment—no external authorization tokens required.

System Prerequisites

Before proceeding, ensure the following tools are installed:

Deployment Steps

Obtain the project source code:

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

Install necessary runtime packages:

bash bun install

Operational Configuration

Launch the Claude desktop client and navigate to Settings -> Developer Options -> Modify Configuration.
Modify the claude_desktop_config.json file by appending the following configuration block:

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

Crucial Note: Substitute <YOUR_USER_NAME> with the actual short name of your macOS user account.

Reinitialize the Claude desktop application for the changes to take effect.
Initiate the indexing process. Prompt Claude with a directive such as: "Commence indexing of my personal notes repository" or "Process all content stored in Apple Notes."

Diagnostic Procedures

To monitor operational events and identify issues, examine the following log streams:

bash tail -n 50 -f ~/Library/Logs/Claude/mcp-server-local-machine.log

Alternatively, check the generic stream:

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

Future Enhancements Roadmap

[ ] Reformat retrieved Apple Notes entries from HTML structure into Markdown before embedding for superior AI consumption.
[ ] Implement advanced content segmentation using recursive or Markdown-aware text splitting strategies.
[ ] Introduce functionality to permit selection of a user-specified alternative embedding generator.
[ ] Provide granular administration tools for the database, including data purging and custom query execution paths.
[x] Successfully implemented persistence mechanism for saving notes back into the Notes application via Claude commands.