henilcalagiya/mcp-apple-notes

Powerful tools for automating Apple Notes using Model Context Protocol (MCP)

mcp-name: io.github.henilcalagiya/mcp-apple-notes

PyPI version License: MIT Python 3.10+

Overview

Apple Notes MCP Server provides seamless integration of Apple Notes with any MCP-compatible client. It enables full note automation — including creating, reading, updating, and deleting notes — through a simple and secure AppleScript API layer.

Features

• Full CRUD support for Apple Notes (Create, Read, Update, Delete)
• Works with Continue.dev, Claude Desktop, Perplexity, and other MCP clients
• Native AppleScript integration for reliable macOS automation
• Comprehensive tools for Apple Notes automation
• Automatic installation via uvx or manual setup
• FastMCP implementation with modern decorator-based API

Requirements

• macOS - Required for AppleScript support
• Python 3.10+ - Required for MCP SDK compatibility
• Apple Notes application - Must be installed and accessible
• MCP-compatible client (e.g., Continue.dev, Claude Desktop)

Quick Start

Step 1: Install uv (if not already installed)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (pip):

pip install uv

Step 2: Add MCP Configuration

Add this configuration to your MCP client:

For Perplexity, Cursor, Continue.dev, Claude Desktop:

{
  "mcpServers": {
    "apple-notes": {
      "command": "uvx",
      "args": ["mcp-apple-notes@latest"]
    }
  }
}

🎉 That's it! Your MCP client will automatically install and run the package when needed.

Note: Ensure your MCP client has permission to access Apple Notes and execute AppleScript commands in System Preferences → Security & Privacy → Privacy → Accessibility.

Available Tools

Note Management (6 tools)

• create_note - Create notes with HTML content
• read_note - Read notes by ID with verification
• update_note - Update notes by ID with HTML content
• delete_note - Delete notes by ID with verification
• move_note - Move notes between folders
• list_all_notes - List all notes across all folders

Folder Management (5 tools)

• create_folder - Create folders with path support
• read_folder - Read folder details by ID
• rename_folder - Rename folders by ID
• delete_folder - Delete folders by ID
• move_folder - Move folders between locations

Search & Structure (3 tools)

• search_notes - Search notes by keywords
• list_folder_with_structure - Show folder hierarchy
• list_notes_with_structure - Show folders + notes hierarchy

Content Support

HTML Formatting: <h1-h6>, <b><i><u>, <p><div><br>, <ul><ol><li>, <table>, <a>

Special Features:

• Unicode and emoji support (🚀, ✅, 📝)
• Nested folder paths (up to 5 levels)
• Automatic character escaping
• Rich content with headers, lists, tables

Architecture

The server follows the MCP protocol specification and is built with a modular architecture:

• AppleScript Layer - Handles direct interaction with Apple Notes
• Tools Layer - Wraps AppleScript operations for MCP tools
• FastMCP Server Layer - Implements MCP protocol using decorators

Troubleshooting

Common Issues

1. "No module named 'mcp'" Error

   • Use uvx for automatic installation
   • Ensure uv is installed and in PATH

2. AppleScript Permission Denied

   • Grant permission to your terminal/MCP client in System Preferences → Security & Privacy → Privacy → Accessibility

3. Notes Not Found

   • Ensure Apple Notes app is installed and accessible
   • Check that notes exist in the default location

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Henil C Alagiya

• GitHub: @henilcalagiya
• LinkedIn: Henil C Alagiya

Support & Contributions:

• 🐛 Report Issues: GitHub Issues
• 💬 Questions: Reach out on LinkedIn
• 🤝 Contributions: Pull requests welcome!