AppleNotesMCP by gillesdelhaes - MCP Server

Apple Notes MCP Server

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

Prerequisites
Installation
- Automated Installation (Recommended)
- Manual Installation
  - Manual Installation with RAG (Full Features)
  - Manual Installation without RAG (Core Features Only)
Configuration
Basic Usage
Advanced Features
Architecture
Troubleshooting
Best Practices
- Note Management
- RAG Usage
Security & Privacy
Advantages of Native Installation
Uninstalling
Support & Resources
Known Limitations
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:

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

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

# 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):

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

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

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

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

#!/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:

#!/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:

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:

{
  "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:

echo $USER

And the full path to your project with:

cd /path/to/AppleNotesMCP
pwd

Permissions Setup

The first time you use the server, macOS will prompt you to grant automation permissions:

Go to System Settings > Privacy & Security > Automation
Find your MCP client in the list (e.g., "Claude Desktop")
Enable the checkbox next to Notes
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

MCP Server (applenotes_server.py): Handles MCP protocol communication and tool execution
RAG System (rag_storage.py): Manages semantic search indexing and retrieval (optional)
AppleScript Bridge: Executes AppleScript commands via osascript
Launch Script (run_server.sh): Activates Python environment and starts server
ChromaDB: Vector database for storing embeddings (RAG only)
Sentence Transformers: Generates embeddings for semantic search (RAG only)

Data Flow

Basic Note Operation

MCP client sends tool request
Server translates to AppleScript
osascript executes the command
Apple Notes performs the action
Result returned through the chain

RAG Semantic Search

MCP client sends search query
Server generates query embedding
ChromaDB performs vector similarity search
Relevant note chunks retrieved
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:

Verify the launch script path in your MCP client config:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Test the launch script directly:
```
./run_server.sh
```

Check that the Python environment exists:

conda env list | grep applenotes-mcp  # For conda
# OR
ls -la applenotes-mcp/  # For venv/uv

Verify dependencies are installed:

conda activate applenotes-mcp  # or source applenotes-mcp/bin/activate
pip list | grep mcp

Check MCP client logs:
```
tail -f ~/Library/Logs/Claude/mcp*.log
```

Tools Not Appearing

Problem: MCP tools don't show up in your client

Solutions:

Ensure the script is executable:
```
chmod +x run_server.sh
```
Restart your MCP client completely (quit and reopen)
Verify the configuration path is correct (use absolute path, not ~)
Check for errors in client logs

Permission Errors

Problem: "Application is not allowed to send keystrokes" or similar errors

Solutions:

Go to System Settings > Privacy & Security > Automation
Find your MCP client (e.g., "Claude Desktop")
Enable the checkbox next to "Notes"
Try using a tool to trigger the permission dialog if it doesn't appear
Restart your MCP client after granting permissions

AppleScript Errors

Problem: Operations fail with AppleScript errors

Solutions:

"Can't get note": Note name or folder may be incorrect (check case sensitivity)
```
"List all my notes"  # To see exact note names
```
"Application not responding": Open Notes app manually first
Notes must be synced: iCloud notes must be synced locally to be accessible
Case sensitivity: Folder and note names are case-sensitive

RAG Not Available

Problem: RAG tools return "RAG system not available"

Solutions:

Install RAG dependencies:

conda activate applenotes-mcp
pip install chromadb sentence-transformers

Verify installation:

python -c "from rag_storage import check_rag_availability; print(check_rag_availability())"

Restart your MCP client completely
Check server logs for RAG initialization messages

Search Returns No Results

Problem: Semantic search finds nothing, but notes exist

Solutions:

Check if notes are indexed:
```
"Show me RAG stats"
```
Index the notes:
```
"Index all my notes"
```
Try a broader query (less specific terms)

Lower the relevance threshold:

"Search for 'topic' with minimum relevance of 40%"

Environment Issues

Problem: Wrong Python version or conda not found

Solutions:

Conda not found - Add explicit path to launch script:

source "$HOME/anaconda3/etc/profile.d/conda.sh"
# or
source "$HOME/miniconda3/etc/profile.d/conda.sh"

Wrong Python version:
```
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:

Check what's indexed:
```
"Show RAG stats"
```

Clear and rebuild selectively:

"Clear the RAG index"
"Index all notes in the Work folder"  # Only what you need

Manually delete and restart:

rm -rf notes_rag_db
# Restart MCP client to recreate fresh index

Best Practices

Note Management

Default account: Most users have notes in "iCloud" account
Default folder: Use "Notes" as default folder if not specified
Search before reading: When looking for specific notes, search first
HTML formatting: When creating formatted notes, refer to note-formatting-guide.md

RAG Usage

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
Maintenance:
- Re-index notes after significant edits
- Remove deleted notes from index
- Periodic full re-indexing (monthly for active users)
Search optimization:
- Use semantic search for exploratory queries
- Use keyword search for specific terms
- Adjust relevance threshold based on needs
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

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

gillesdelhaes/AppleNotesMCP

Apple Notes MCP Server

Overview

Key Features

Table of Contents

Prerequisites

Installation

Automated Installation (Recommended)

Manual Installation

Manual Installation with RAG (Full Features)

Manual Installation without RAG (Core Features Only)

Configuration

Launch Script Setup (Manual Installation Only)

For Conda Users

For uv or venv Users

MCP Client Configuration

Permissions Setup

Basic Usage

Core Operations

Listing Notes

Creating Notes

Reading Notes

Updating Notes

Deleting Notes

Folder Management

Listing Folders

Creating Folders

Moving Notes

Deleting Folders

Search Operations

Keyword Search

Account Management

Advanced Features

RAG Semantic Search

First-Time Setup

Semantic Search

Getting Full Note Context

Indexing Individual Notes

Batch Indexing

Related Notes Discovery

Smart Suggestions

RAG Statistics and Management

Check Index Status

Get Topics Overview

Managing the Index

When to Use RAG vs Regular Search

Architecture

System Architecture

Components

Data Flow

Basic Note Operation

RAG Semantic Search

Storage

Technical Details

Troubleshooting

Server Not Starting

Tools Not Appearing

Permission Errors

AppleScript Errors

RAG Not Available

Search Returns No Results

Environment Issues

Index Size Growing Large

Best Practices

Note Management

RAG Usage

Security & Privacy

Advantages of Native Installation

Uninstalling

Support & Resources

Known Limitations

License