MCP Apple Notes MCP Server: Semantic Search & Retrieval Augmented Generation Integration

Overview: What is MCP Apple Notes MCP Server?

MCP Apple Notes is an MCP (Model Context Protocol) server that integrates semantic search capabilities and retrieval-augmented generation features over your Apple Notes data. This solution leverages the Model Context Protocol to provide a powerful, local AI assistant integration for developers building intelligent applications with Claude Desktop and other compatible MCP clients.

🔧 Core Features & MCP Capabilities

The MCP Apple Notes MCP Server introduces several key features that enhance its value as an AI application integrator:

Semantic Search

MCP Apple Notes utilizes the all-MiniLM-L6-v2 on-device embedding model to enable semantic search over your Apple Notes. This means that AI applications can understand and retrieve notes based on their content context, not just exact matches.

Full-Text Search

In addition to semantic search, this server supports full-text search, providing thorough searching capabilities across all notes in your collection.

Vector Storage

Data is managed using LanceDB for efficient vector storage, allowing quick retrieval of relevant notes when queried by the AI application.

MCP Compatibility

The server is designed to be fully MCP-compatible, enabling seamless integration with various AI clients. Currently, official support includes Claude Desktop, and compatibility with Continue and Cursor is planned in future releases.

Apple Notes Integration

MCP Apple Notes integrates directly with Apple Notes using JavaScript for Automation (JXA), ensuring that your notes are easily accessible by the server without requiring external APIs or services.

Local Execution

The solution operates exclusively on your local machine, allowing full control over data privacy and eliminating the need for API keys.

⚙️ MCP Architecture & Protocol Implementation

MCP Apple Notes is built to adhere strictly to the Model Context Protocol (MCP) framework. It consists of a server component that listens for requests from MCP clients and performs data operations based on those instructions.

MCP Protocol Flow

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Data Architecture

The server uses LanceDB for vector storage and supports the embedding of notes in Markdown format. This allows for rich presentation and formatting within AI applications.

🚀 Getting Started with Installation

To get started, follow these steps to install and configure your MCP Apple Notes server:

1. Clone the Repository:

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

2. Install Dependencies: Use Bun to manage dependencies:

   bun install
   

3. Configure the MCP Client:

   • Open Claude Desktop and navigate to Settings -> Developer -> Edit Config.
   • Add the following configuration entry to claude_desktop_config.json:

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

   • Replace <YOUR_USER_NAME> with your actual username.

4. Start the Server:

   • Restart Claude Desktop to ensure configuration is applied.
   • After restarting, you should see Connected status for the local-machine MCP server in the app settings.

5. Index Your Notes: Ask Claude to index your notes by saying something like "Index my notes" or "Index my Apple Notes".

💡 Key Use Cases in AI Workflows

Case Study 1: Enhancing Legal Research

AI applications can use MCP Apple Notes as a backend data source for legal research. By indexing relevant documents and cases, users can receive contextual search results directly from the stored data.

Case Study 2: Personalized Health Advice

Integrate this server into health-related applications to provide personalized advice based on user notes and medical records. The semantic search capabilities ensure that AI assistants can understand and respond to queries in a contextually relevant manner.

🔌 Integration with MCP Clients

MCP Apple Notes is designed to be compatible with the following MCP clients:

MCP Client	Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	✅
Cursor	❌	✅	❌

📊 Performance & Compatibility Matrix

While currently supporting full compatibility with both Claude and Continue, Cursor integration is limited to tools usage due to technical constraints.

🛠️ Advanced Configuration & Security

For advanced users, you can customize the server configuration by modifying the mcpServers entry in your claude_desktop_config.json.

{
  "mcpServers": {
    "[server-name]": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-[name]"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

❓ Frequently Asked Questions (FAQ)

Q1: Can I use a different embeddings model?

Yes, you can choose to use another embedding model by customizing the server arguments. The default is all-MiniLM-L6-v2 but other models like sentence-transformers/all-mpnet-base-v2 are also supported.

Q2: How do I troubleshoot if I am not seeing any data?

Refer to troubleshooting steps, which include checking logs for errors using:

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

Q3: Can I purge notes from the server storage?

While purging functionality is not natively supported, you can implement custom functions to clear or manage stored data.

Q4: Does this solution work with Windows or Linux systems?

The current implementation requires system-specific scripts and may need modifications for broader OS support. However, Bun supports Windows and macOS out of the box.

Q5: Are there any limitations on the size of notes that can be indexed?

There are no strict size limits beyond what your storage and memory constraints allow. However, performance might degrade with very large datasets without optimizations.

👩‍💻 Development & Contribution Guidelines

Contributions to MCP Apple Notes help improve the overall MCP ecosystem. If you wish to contribute, feel free to contribute patches or even complete new features by forking the repository, making your changes, and submitting a pull request.

To get started:

1. Fork this repository.
2. Implement your feature or fix.
3. Create a PR with clear instructions for testing.

🌐 MCP Ecosystem & Resources

Join the community to discover more about Model Context Protocol (MCP) and its applications in various AI projects. Explore resources, participate in discussions, and stay updated on the latest developments with MCP and our growing ecosystem.

By integrating this server into your project, you enhance the capabilities of Claude Desktop and other MCP clients through seamless local execution and rich data management.