🍎 Enhanced Apple Notes MCP Server

An advanced Model Context Protocol (MCP) server that provides comprehensive Apple Notes integration with enhanced features for knowledge management workflows. Built for Claude Desktop with full CRUD operations, search capabilities, and bulk processing tools.

📚 Table of Contents

• Why Enhanced?
• Features
• Installation
• Available Tools
• Usage Examples
• Architecture
• Troubleshooting
• Performance
• Contributing
• License

🚀 Why Enhanced?

This server extends the original apple-notes-mcp with powerful additional features:

Feature	Original	Enhanced	Description
Basic CRUD	✅	✅	Create, read, update, delete notes
Search Notes	❌	✅	Search by title and content
Folder Management	❌	✅	Create and list folders
Bulk Export	❌	✅	Export multiple notes (JSON/Markdown)
Advanced Filtering	❌	✅	Filter by folder with pagination
Large Dataset Support	❌	✅	50MB buffer with pagination
Error Handling	Basic	Enhanced	Comprehensive error management

✨ Features

🔧 Core Operations

• 📝 Create Notes: Create new notes with title and content
• 📖 Read Notes: Retrieve note content by name
• ✏️ Update Notes: Modify existing note content
• 📋 List Notes: List notes with filtering and pagination

🚀 Enhanced Features

• 🔍 Search Notes: Find notes by title or content across all folders
• 📁 Folder Management: Create new folders and list existing ones
• 📦 Bulk Export: Export multiple notes in JSON or Markdown format
• 🎯 Advanced Filtering: Filter by folder with configurable limits
• 🛡️ Security: Local-only operations, no external network calls

🛠️ Installation

Prerequisites

• macOS with Apple Notes app installed
• Node.js >= 16.0.0
• Claude Desktop with MCP support

Quick Setup

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Test the server:

   npm test

4. Add to Claude Desktop:

   # Global installation (recommended)
   claude mcp add --scope user apple-notes-enhanced -- node /path/to/apple-notes-mcp/server/index.js
   
   # Or with absolute path
   claude mcp add --scope user apple-notes-enhanced -- node "$(pwd)/server/index.js"

5. Verify installation:

   claude mcp list
   # Should show: apple-notes-enhanced - ✓ Connected

macOS Permissions

Grant necessary permissions for AppleScript automation:

1. System Preferences → Security & Privacy → Privacy → Accessibility
2. Add Terminal or Claude Desktop to the allowed applications
3. Restart Claude Desktop after granting permissions

🎯 Available Tools

1. list_notes

List all notes with optional filtering and pagination.

{
  "folder": "Personal",      // Optional: filter by folder name
  "limit": 20               // Optional: max results (default: 20)
}

Response: Array of note objects with metadata.

2. search_notes

Search notes by title or content across your Apple Notes.

{
  "query": "meeting notes",   // Required: search term
  "folder": "Work",          // Optional: search within specific folder
  "limit": 10               // Optional: max results (default: 10)
}

Response: Array of matching notes with highlighted search context.

3. get_note_content

Retrieve the full content of a specific note.

{
  "note_name": "Project Planning",  // Required: exact note title
  "folder": "Work"                 // Optional: folder hint for faster lookup
}

Response: Full note content in HTML format.

4. add_note

Create a new note in the specified folder.

{
  "name": "Daily Standup",          // Required: note title
  "content": "Meeting agenda...",   // Required: note content
  "folder": "Work"                 // Optional: target folder (default: "Notes")
}

Response: Confirmation with created note details.

5. update_note_content

Update the content of an existing note.

{
  "note_name": "Project Status",   // Required: note to update
  "new_content": "Updated info",   // Required: new content
  "folder": "Work"                // Optional: folder hint
}

Response: Confirmation with updated note details.

6. list_folders

List all available folders in Apple Notes.

{}  // No parameters required

Response: Array of folder objects with names and IDs.

7. create_folder

Create a new folder in Apple Notes.

{
  "folder_name": "Project Alpha"   // Required: name for new folder
}

Response: Confirmation with created folder details.

8. bulk_export

Export multiple notes with metadata in various formats.

{
  "folder": "Personal",           // Optional: export from specific folder
  "format": "markdown",          // Optional: "json" or "markdown" (default)
  "limit": 50                   // Optional: max notes to export (default: 50)
}

Response: Exported notes in requested format with metadata.

💡 Usage Examples

Basic Note Management

# List recent notes
"List my 10 most recent notes in the Work folder"

# Search for content
"Search for notes containing 'project deadline' in Apple Notes"

# Create a daily note
"Create a note called 'Daily Journal 2024-01-15' with today's agenda"

Advanced Workflows

# Export knowledge base
"Export all notes from my 'Research' folder as markdown format"

# Organize notes
"Create a new folder called 'AI Projects' and list all existing folders"

# Bulk operations
"Find all notes about Python programming and export them as JSON"

Knowledge Management Integration

# Prepare for migration
"Export all permanent notes for migration to Notion"

# Cross-platform workflow
"List all folders and their note counts for organization review"

# Project organization
"Search for all notes containing 'trading bot' and create a summary"

🏗️ Architecture

Technical Stack

• MCP SDK: @modelcontextprotocol/sdk v1.11.3
• Runtime: Node.js with native child_process integration
• Automation: AppleScript via osascript for native macOS integration
• Security: Local-only execution, no external dependencies

AppleScript Integration

The server uses AppleScript to interact directly with the Apple Notes app:

• Native macOS automation through osascript
• Proper text escaping for special characters
• Folder-aware operations for better organization
• Efficient bulk operations with pagination support

Security Model

• 🔒 Local Operations: All processing happens on your machine
• 🚫 No Network Calls: Zero external API requests or data transmission
• 🛡️ Sandboxed: Operates within macOS security constraints
• ✅ Permission-Based: Requires explicit macOS accessibility permissions

🐛 Troubleshooting

Common Issues

AppleScript Permission Denied:

# Solution: Grant accessibility permissions
System Preferences → Security & Privacy → Privacy → Accessibility
# Add Terminal, Claude Desktop, or your terminal application

Notes App Not Responding:

# Solution: Initialize Notes app
open -a Notes
# Wait for app to fully load, then retry

MCP Server Connection Failed:

# Check server status
claude mcp list

# Reinstall if needed
claude mcp remove apple-notes-enhanced
claude mcp add --scope user apple-notes-enhanced -- node /path/to/server/index.js

Bulk Export Buffer Exceeded:

# Use smaller batch sizes
# The server automatically limits to 50 notes per export
# For larger datasets, export by folder or use multiple calls

Debug Commands

# Test AppleScript directly
osascript -e 'tell application "Notes" to return count of notes'

# Test server manually
node server/index.js

# Verify MCP configuration
claude mcp list | grep apple-notes

Performance Optimization

For Large Note Collections (1000+ notes):

• Use folder-based filtering for faster queries
• Implement pagination with smaller limit values
• Consider bulk export in multiple batches

Memory Management:

• Server uses 50MB buffer limit for bulk operations
• Automatic pagination prevents memory overflow
• Stateless design ensures minimal memory footprint

📈 Performance

Metric	Specification
Response Time	100-500ms per operation
Concurrent Operations	Single-threaded AppleScript execution
Memory Usage	Minimal, stateless server design
Scalability	Optimized for personal use (100s-1000s notes)
Buffer Limit	50MB for bulk operations
Batch Size	Up to 50 notes per bulk export

🔮 Future Enhancements

Planned Features

• Rich Text Preservation: Enhanced formatting support
• Attachment Handling: Images, files, and link management
• Template System: Pre-defined note structures
• Real-time Sync: Live updates and change notifications
• Advanced Search: Regex patterns and tag-based filtering
• Backup Integration: Automated versioning and recovery

Workflow Integrations

• Shortcuts App: Native macOS automation workflows
• Calendar Sync: Date-based note organization
• Contact Integration: People-based note tagging
• Location Services: Geographic note capture

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Report Issues: Use GitHub Issues for bugs and feature requests
2. Submit PRs: Fork the repo and submit pull requests
3. Improve Documentation: Help make the docs clearer
4. Share Use Cases: Tell us how you use the server

Development Setup

# Clone for development
git clone https://github.com/ReinaMacCredy/apple-notes-mcp.git
cd apple-notes-mcp

# Install dependencies
npm install

# Run tests
npm test

# Test server locally
node server/index.js

Code Standards

• Follow ESLint configuration
• Add tests for new features
• Update documentation for API changes
• Ensure AppleScript compatibility

📄 License

MIT License - See LICENSE file for details.

---

Questions or Issues? Please open a GitHub Issue or check our troubleshooting guide.

⭐ Found this useful? Give us a star on GitHub to help others discover this enhanced Apple Notes integration!