Content
# Apple Notes MCP Server
[](https://www.apple.com/macos/)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
A powerful Model Context Protocol (MCP) server that enables AI assistants to interact with Apple Notes on macOS through AppleScript, featuring advanced semantic search capabilities powered by RAG (Retrieval-Augmented Generation).
## Overview
This MCP server provides secure, local access to your Apple Notes application, allowing your AI assistant to create, read, update, delete, search, and organize notes directly from any MCP-compatible client. The server includes optional RAG functionality for semantic search, enabling meaning-based queries beyond simple keyword matching.
### Key Features
✅ **Complete Notes Management**
- Create, read, update, and delete notes
- List and organize folders
- Move notes between folders
- Search across all notes
✅ **Multi-Account Support**
- Works with iCloud and "On My Mac" accounts
- Manage multiple Notes accounts simultaneously
- Account-aware operations
✅ **Semantic Search (Optional RAG)**
- Find notes by meaning, not just keywords
- Intelligent chunking for better retrieval
- Relevance scoring and filtering
- Batch indexing capabilities
✅ **Native macOS Integration**
- Direct AppleScript integration
- No Docker or containerization required
- Fast execution with system-level access
- Proper macOS permissions handling
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Automated Installation (Recommended)](#automated-installation-recommended)
- [Manual Installation](#manual-installation)
- [Manual Installation with RAG (Full Features)](#manual-installation-with-rag-full-features)
- [Manual Installation without RAG (Core Features Only)](#manual-installation-without-rag-core-features-only)
- [Configuration](#configuration)
- [Launch Script Setup (Manual Installation Only)](#launch-script-setup-manual-installation-only)
- [MCP Client Configuration](#mcp-client-configuration)
- [Permissions Setup](#permissions-setup)
- [Basic Usage](#basic-usage)
- [Core Operations](#core-operations)
- [Folder Management](#folder-management)
- [Search Operations](#search-operations)
- [Advanced Features](#advanced-features)
- [RAG Semantic Search](#rag-semantic-search)
- [Batch Indexing](#batch-indexing)
- [Related Notes Discovery](#related-notes-discovery)
- [Smart Suggestions](#smart-suggestions)
- [RAG Statistics and Management](#rag-statistics-and-management)
- [When to Use RAG vs Regular Search](#when-to-use-rag-vs-regular-search)
- [Architecture](#architecture)
- [System Architecture](#system-architecture)
- [Components](#components)
- [Data Flow](#data-flow)
- [Storage](#storage)
- [Technical Details](#technical-details)
- [Troubleshooting](#troubleshooting)
- [Server Not Starting](#server-not-starting)
- [Tools Not Appearing](#tools-not-appearing)
- [Permission Errors](#permission-errors)
- [AppleScript Errors](#applescript-errors)
- [RAG Not Available](#rag-not-available)
- [Search Returns No Results](#search-returns-no-results)
- [Environment Issues](#environment-issues)
- [Index Size Growing Large](#index-size-growing-large)
- [Best Practices](#best-practices)
- [Note Management](#note-management)
- [RAG Usage](#rag-usage)
- [Security & Privacy](#security--privacy)
- [Advantages of Native Installation](#advantages-of-native-installation)
- [Uninstalling](#uninstalling)
- [Support & Resources](#support--resources)
- [Known Limitations](#known-limitations)
- [License](#license)
## Prerequisites
- **macOS operating system** (required for Apple Notes and AppleScript)
- **Apple Notes app** installed and configured
- **Python 3.11 or higher**
- **Python environment manager**: conda (recommended), uv, or venv
- **MCP-compatible client** (e.g., Claude Desktop, or any other MCP client)
- **Automation permissions** for your MCP client to control Notes (configured in System Settings)
## Installation
### Automated Installation (Recommended)
The easiest way to install with full functionality including RAG:
```bash
# Navigate to the project directory
cd /path/to/AppleNotesMCP
# Run the installation script
chmod +x install.sh
./install.sh
```
**What the script does:**
- ✅ Detects and sets up your Python environment (conda or venv)
- ✅ Installs all dependencies including RAG components
- ✅ Downloads the embedding model (~80MB)
- ✅ Creates the launch script (`run_server.sh`)
- ✅ Detects installed MCP clients (Claude Desktop, LM Studio)
- ✅ Provides configuration instructions for your client
- ✅ Verifies the installation
**Supported Python environment managers:**
- **conda** (recommended) - Automatically used if available
- **venv** - Used as fallback if conda not available
The script will automatically detect the best available Python 3.11+ installation.
### Manual Installation
If you prefer manual installation or need more control:
#### Manual Installation with RAG (Full Features)
**Using Conda:**
```bash
# Create and activate environment
conda create -n applenotes-mcp python=3.11 -y
conda activate applenotes-mcp
# Install all dependencies
pip install -r requirements.txt
```
**Using venv:**
```bash
# Create virtual environment (Python 3.11+)
python3 -m venv applenotes-mcp
# Activate environment
source applenotes-mcp/bin/activate
# Install all dependencies
pip install -r requirements.txt
```
**Using uv (Fast Alternative):**
```bash
# Create and activate environment
uv venv applenotes-mcp --python 3.11
source applenotes-mcp/bin/activate
# Install all dependencies
uv pip install -r requirements.txt
```
**Dependencies installed:**
- `mcp[cli]>=1.2.0` - Model Context Protocol framework
- `chromadb>=0.4.22` - Vector database for semantic search
- `sentence-transformers>=2.2.2` - Embedding model for semantic search
The first time you use RAG features, the system will automatically download the `all-MiniLM-L6-v2` embedding model (~80MB).
#### Manual Installation without RAG (Core Features Only)
If you only want basic note management without semantic search:
**Using Conda:**
```bash
# Create and activate environment
conda create -n applenotes-mcp python=3.11 -y
conda activate applenotes-mcp
# Install core dependencies only
pip install mcp[cli]>=1.2.0
```
**Using venv:**
```bash
# Create and activate environment
python3 -m venv applenotes-mcp
source applenotes-mcp/bin/activate
# Install core dependencies only
pip install mcp[cli]>=1.2.0
```
**Using uv:**
```bash
# Create and activate environment
uv venv applenotes-mcp --python 3.11
source applenotes-mcp/bin/activate
# Install core dependencies only
uv pip install mcp[cli]>=1.2.0
```
## Configuration
> **Note:** If you used the automated installation script (`install.sh`), the launch script (`run_server.sh`) has already been created for you. Skip to [MCP Client Configuration](#mcp-client-configuration) and use the configuration shown by the installation script.
### Launch Script Setup (Manual Installation Only)
For manual installations, create a launch script that your MCP client will use to start the server:
#### For Conda Users
Create `run_server.sh`:
```bash
#!/bin/bash
# Get the directory where this script is located
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
# Activate conda environment
source "$(conda info --base)/etc/profile.d/conda.sh"
conda activate applenotes-mcp
# Run the server
cd "$SCRIPT_DIR"
python applenotes_server.py
```
#### For uv or venv Users
Create `run_server.sh`:
```bash
#!/bin/bash
# Get the directory where this script is located
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
# Activate virtual environment
source "$SCRIPT_DIR/applenotes-mcp/bin/activate"
# Run the server
cd "$SCRIPT_DIR"
python applenotes_server.py
```
Make the script executable:
```bash
chmod +x run_server.sh
```
### MCP Client Configuration
> **Note:** If you used the automated installation script (`install.sh`), it detected your MCP clients and provided the configuration. Use those instructions. The information below is for manual configuration.
Configure your MCP client to use the server. For **Claude Desktop**, edit the configuration file:
**Configuration file location:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Add this configuration:**
```json
{
"mcpServers": {
"applenotes": {
"command": "/bin/bash",
"args": [
"/Users/YOUR_USERNAME/path/to/AppleNotesMCP/run_server.sh"
]
}
}
}
```
**Important:** Replace `/Users/YOUR_USERNAME/path/to/AppleNotesMCP/run_server.sh` with the actual full path to your `run_server.sh` file.
You can find your username with:
```bash
echo $USER
```
And the full path to your project with:
```bash
cd /path/to/AppleNotesMCP
pwd
```
### Permissions Setup
The first time you use the server, macOS will prompt you to grant automation permissions:
1. Go to **System Settings** > **Privacy & Security** > **Automation**
2. Find your MCP client in the list (e.g., "Claude Desktop")
3. Enable the checkbox next to **Notes**
4. Restart your MCP client completely
If the permission dialog doesn't appear automatically, try using a tool once to trigger it.
## Basic Usage
### Core Operations
Always refer to `note-formatting-guide.md` before creating formatted notes. This guide contains information on how to format notes so they display correctly in various scenarios.
#### Listing Notes
```
"List all my notes"
"List notes in the Work folder"
"Show me all notes in my On My Mac account"
```
#### Creating Notes
```
"Create a new note called 'Shopping List' with the content 'milk, eggs, bread'"
"Create a note called 'Meeting Notes' in the Work folder"
```
**Note:** If the specified folder doesn't exist, it will be created automatically.
#### Reading Notes
```
"Read the note called 'Todo List'"
"Show me the content of 'Project Ideas' from the Work folder"
```
#### Updating Notes
```
"Update the note 'Shopping List' with 'milk, eggs, bread, cheese'"
"Edit the note 'Meeting Notes' to add today's discussion points"
```
#### Deleting Notes
```
"Delete the note 'Old Draft'"
"Remove the note 'Temporary' from the Archive folder"
```
**Warning:** Deletion is permanent and cannot be undone through the server.
### Folder Management
#### Listing Folders
```
"List all my folders"
"Show me all folders in my iCloud account"
```
#### Creating Folders
```
"Create a folder called 'Work'"
"Make a new folder named 'Personal Projects'"
```
#### Moving Notes
```
"Move the note 'Vacation Plans' to the Personal folder"
"Move 'Budget Report' from Archive to Work"
```
#### Deleting Folders
```
"Delete the folder 'Old Projects'"
```
**Note:** Folders must be empty before they can be deleted.
### Search Operations
#### Keyword Search
```
"Search for notes containing 'project deadline'"
"Find notes about 'vacation'"
```
Keyword search performs case-insensitive text matching across note names and bodies.
#### Account Management
```
"Show me all my Notes accounts"
"List available accounts"
```
This typically shows "iCloud" and "On My Mac" accounts.
## Advanced Features
### RAG Semantic Search
RAG (Retrieval-Augmented Generation) enables semantic search based on **meaning** rather than just keywords.
**Example comparison:**
- **Keyword search**: "budget meeting" → finds only exact phrase matches
- **Semantic search**: "budget meeting" → finds "financial planning session", "Q3 spending review", "cost reduction talks", etc.
#### First-Time Setup
Before using semantic search, index your notes:
```
"Index all my notes for semantic search"
```
This process:
- Reads all your notes
- Splits them into meaningful chunks
- Generates embeddings (vector representations)
- Stores them in a local database (`./notes_rag_db/`)
#### Semantic Search
```
"Search semantically for 'machine learning projects'"
"Find notes about 'vacation planning' using semantic search"
"Semantically search for 'budget discussion' in the Work folder"
```
**Search results include:**
- Note name and location
- Relevance score (0-100%)
- Relevant excerpt from the note
- Chunk information
#### Getting Full Note Context
After finding a relevant note through semantic search, retrieve its complete content:
```
"Get the full context of 'Project Ideas'"
"Show me the complete content of that note"
```
This retrieves all indexed chunks of the note and combines them into the full text.
#### Indexing Individual Notes
Index specific notes as you create or update them:
```
"Create a note called 'Q4 Planning' and index it for semantic search"
"Index the note 'Meeting Notes' for semantic search"
```
### Batch Indexing
Index multiple notes at once:
```
"Index all notes in the Work folder"
"Index all my notes"
```
**Performance note:** Indexing is CPU-intensive. For large collections (100+ notes), consider indexing during downtime.
**Example output:**
```
✅ Batch indexing complete
📊 Indexed: 47 notes
❌ Failed: 0 notes
📝 Total chunks created: 156
📚 Index now contains: 156 chunks from 47 notes
```
### Related Notes Discovery
Find notes semantically similar to a specific note:
```
"Find notes related to 'Project Planning'"
"Show me notes similar to 'Research Ideas'"
```
This feature:
- Retrieves the full context of the source note
- Uses it as a search query
- Finds the most similar notes
- Filters out the source note itself
### Smart Suggestions
Get intelligent note suggestions with automatic relevance filtering:
```
"Suggest notes for 'machine learning best practices'"
"What notes can help me with 'project management strategies'?"
```
**Features:**
- Automatic relevance filtering (default: 60% minimum)
- Only returns reasonably relevant results
- Reduces noise in search results
### RAG Statistics and Management
#### Check Index Status
```
"Show me RAG statistics"
"How many notes are indexed?"
```
**Example output:**
```
📊 RAG Index Statistics:
📝 Total chunks: 156
📚 Unique notes indexed: 47
🗂️ Collection name: apple_notes
💾 Storage path: ./notes_rag_db
```
#### Get Topics Overview
```
"Show me an overview of indexed topics"
"What's in my RAG index?"
```
This displays:
- Total notes and chunks
- Average chunks per note
- Accounts with indexed notes
- Folders with indexed content
#### Managing the Index
**Remove a note from index:**
```
"Remove the note 'Old Draft' from the search index"
```
**Clear entire index:**
```
"Clear the RAG index"
```
**Warning:** Clearing the index cannot be undone. All notes will need to be re-indexed.
### When to Use RAG vs Regular Search
**Use RAG semantic search when:**
- You remember the topic but not exact wording
- You want conceptually related notes
- You're exploring a theme across multiple notes
- You want smart, meaning-based results
**Use regular keyword search when:**
- You know the exact phrase or word
- You're looking for a specific name or term
- Speed is critical (keyword search is faster)
- You want exact matches only
## Architecture
### System Architecture
```
MCP Client (e.g., Claude Desktop, any MCP-compatible client)
↓ (MCP Protocol via stdio)
Python MCP Server (applenotes_server.py)
↓ (subprocess.run)
osascript command
↓ (AppleScript)
Apple Notes App
↓
Local macOS System
```
### Components
1. **MCP Server (`applenotes_server.py`)**: Handles MCP protocol communication and tool execution
2. **RAG System (`rag_storage.py`)**: Manages semantic search indexing and retrieval (optional)
3. **AppleScript Bridge**: Executes AppleScript commands via `osascript`
4. **Launch Script (`run_server.sh`)**: Activates Python environment and starts server
5. **ChromaDB**: Vector database for storing embeddings (RAG only)
6. **Sentence Transformers**: Generates embeddings for semantic search (RAG only)
### Data Flow
#### Basic Note Operation
1. MCP client sends tool request
2. Server translates to AppleScript
3. `osascript` executes the command
4. Apple Notes performs the action
5. Result returned through the chain
#### RAG Semantic Search
1. MCP client sends search query
2. Server generates query embedding
3. ChromaDB performs vector similarity search
4. Relevant note chunks retrieved
5. Results formatted and returned
### Storage
**RAG Index Location:**
```
/path/to/AppleNotesMCP/
├── applenotes_server.py
├── rag_storage.py
├── run_server.sh
└── notes_rag_db/ ← ChromaDB storage
├── chroma.sqlite3 ← Database file
└── ... ← Index files
```
The index persists between server restarts, so notes only need to be indexed once (unless they change).
### Technical Details
**AppleScript Execution:**
- All Notes interactions use AppleScript via `osascript`
- 30-second timeout on all operations
- Proper string escaping for quotes and backslashes
**RAG Implementation:**
- Embedding model: `all-MiniLM-L6-v2` (384-dimensional vectors)
- Chunk size: ~1000 characters with 200-character overlap
- Semantic chunking: Respects paragraph boundaries
- Similarity metric: Cosine similarity
- HTML cleaning: Strips formatting before indexing
**HTML Formatting:**
Notes uses HTML for formatting. The server handles HTML in both directions:
- Creating notes: Wraps content in proper HTML structure
- Reading notes: Returns raw HTML (may need parsing)
- Indexing (RAG): Strips HTML for clean text embeddings
## Troubleshooting
### Server Not Starting
**Problem:** MCP client can't connect to the server
**Solutions:**
1. Verify the launch script path in your MCP client config:
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. Test the launch script directly:
```bash
./run_server.sh
```
3. Check that the Python environment exists:
```bash
conda env list | grep applenotes-mcp # For conda
# OR
ls -la applenotes-mcp/ # For venv/uv
```
4. Verify dependencies are installed:
```bash
conda activate applenotes-mcp # or source applenotes-mcp/bin/activate
pip list | grep mcp
```
5. Check MCP client logs:
```bash
tail -f ~/Library/Logs/Claude/mcp*.log
```
### Tools Not Appearing
**Problem:** MCP tools don't show up in your client
**Solutions:**
1. Ensure the script is executable:
```bash
chmod +x run_server.sh
```
2. Restart your MCP client completely (quit and reopen)
3. Verify the configuration path is correct (use absolute path, not ~)
4. Check for errors in client logs
### Permission Errors
**Problem:** "Application is not allowed to send keystrokes" or similar errors
**Solutions:**
1. Go to **System Settings** > **Privacy & Security** > **Automation**
2. Find your MCP client (e.g., "Claude Desktop")
3. Enable the checkbox next to "Notes"
4. Try using a tool to trigger the permission dialog if it doesn't appear
5. Restart your MCP client after granting permissions
### AppleScript Errors
**Problem:** Operations fail with AppleScript errors
**Solutions:**
1. **"Can't get note"**: Note name or folder may be incorrect (check case sensitivity)
```
"List all my notes" # To see exact note names
```
2. **"Application not responding"**: Open Notes app manually first
3. **Notes must be synced**: iCloud notes must be synced locally to be accessible
4. **Case sensitivity**: Folder and note names are case-sensitive
### RAG Not Available
**Problem:** RAG tools return "RAG system not available"
**Solutions:**
1. Install RAG dependencies:
```bash
conda activate applenotes-mcp
pip install chromadb sentence-transformers
```
2. Verify installation:
```bash
python -c "from rag_storage import check_rag_availability; print(check_rag_availability())"
```
3. Restart your MCP client completely
4. Check server logs for RAG initialization messages
### Search Returns No Results
**Problem:** Semantic search finds nothing, but notes exist
**Solutions:**
1. Check if notes are indexed:
```
"Show me RAG stats"
```
2. Index the notes:
```
"Index all my notes"
```
3. Try a broader query (less specific terms)
4. Lower the relevance threshold:
```
"Search for 'topic' with minimum relevance of 40%"
```
### Environment Issues
**Problem:** Wrong Python version or conda not found
**Solutions:**
1. **Conda not found** - Add explicit path to launch script:
```bash
source "$HOME/anaconda3/etc/profile.d/conda.sh"
# or
source "$HOME/miniconda3/etc/profile.d/conda.sh"
```
2. **Wrong Python version**:
```bash
python --version # Should be 3.11 or higher
```
If wrong, recreate the environment with Python 3.11+
### Index Size Growing Large
**Problem:** `notes_rag_db` directory using too much disk space
**Solutions:**
1. Check what's indexed:
```
"Show RAG stats"
```
2. Clear and rebuild selectively:
```
"Clear the RAG index"
"Index all notes in the Work folder" # Only what you need
```
3. Manually delete and restart:
```bash
rm -rf notes_rag_db
# Restart MCP client to recreate fresh index
```
## Best Practices
### Note Management
1. **Default account**: Most users have notes in "iCloud" account
2. **Default folder**: Use "Notes" as default folder if not specified
3. **Search before reading**: When looking for specific notes, search first
4. **HTML formatting**: When creating formatted notes, refer to `note-formatting-guide.md`
### RAG Usage
1. **Index strategy**: Choose one approach:
- **Index everything**: Best for most users, do it once during setup
- **Selective indexing**: Only index important folders
- **As-needed**: Index notes individually as you create them
2. **Maintenance**:
- Re-index notes after significant edits
- Remove deleted notes from index
- Periodic full re-indexing (monthly for active users)
3. **Search optimization**:
- Use semantic search for exploratory queries
- Use keyword search for specific terms
- Adjust relevance threshold based on needs
4. **Performance**:
- Index during downtime (CPU-intensive)
- Limit search results (default 5 is good)
- For 100+ notes, batch index once rather than individually
## Security & Privacy
✅ **All operations are local** - No data leaves your Mac
✅ **No cloud services** - RAG embeddings generated locally
✅ **No logging of content** - Note content never logged
✅ **User permissions** - Runs with your user privileges
✅ **macOS security** - Uses system-level permission controls
✅ **Model download** - Only the embedding model download requires internet (one-time, ~80MB)
## Advantages of Native Installation
✅ **Direct system access** - No Docker overhead
✅ **Faster execution** - Native AppleScript performance
✅ **Simpler debugging** - Direct terminal output
✅ **Full macOS integration** - Works with all system features
✅ **Easy modifications** - Direct code access
✅ **No daemon required** - No Docker daemon overhead
## Uninstalling
```bash
# Remove the conda environment
conda deactivate
conda remove -n applenotes-mcp --all -y
# OR remove venv/uv environment
rm -rf applenotes-mcp
# Remove RAG database (optional)
rm -rf notes_rag_db
# Remove from MCP client config
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# Remove the "applenotes" entry
# Restart your MCP client
```
## Support & Resources
- **Issues**: Open GitHub issues with detailed error messages and reproduction steps
## Known Limitations
- **macOS only**: AppleScript only works on macOS
- **No attachments**: Cannot handle note attachments (images, files, etc.)
- **HTML content**: Note bodies contain HTML which may need parsing by your client
- **iCloud sync**: iCloud notes must be synced locally to be accessible
- **No locking**: Cannot unlock password-protected notes
- **Empty folders**: Folders must be empty to be deleted
- **English-optimized RAG**: Embedding model works best with English text
- **No multimedia RAG**: Can't search images, attachments, or handwriting
## License
MIT License - See LICENSE file for details
---
**Last Updated:** November 2025
**Platform:** macOS only
**Python:** 3.11+
**MCP Version:** 1.2.0+
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available