Skip to main content
Glama
Sign In
io.github.henilcalagiya/mcp-apple-notes

io.github.henilcalagiya/mcp-apple-notes

by henilcalagiya
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Apple Notes MCP Server

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.

Related MCP server: MCP Apple Notes

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

Support & Contributions:

  • 🐛 Report Issues: GitHub Issues

  • 💬 Questions: Reach out on LinkedIn

  • 🤝 Contributions: Pull requests welcome!

Available Tools

14 tools
create_folderA

Create a folder in Apple Notes.

Features:

  • Creates folders at root level or nested paths (up to 5 levels deep)

  • Unicode and emoji support for international characters

  • Duplicate name detection and comprehensive validation

  • iCloud account support

  • Only creates folder if parent path exists

Validation:

  • Max 128 characters, no special chars: < > : " | ? *

  • Parent paths must exist, prevents duplicates

  • Will throw error if parent path doesn't exist

Inputs: folder_name (required), folder_path. Returns: result

create_noteA

Create a new note with specified name and content.

Supported HTML: , , , , , Best Practices: Use semantic HTML, add tags for spacing, avoid CSS styles Folders: Root level or nested paths (up to 5 levels deep) Limitations: No special chars in name, no complex CSS/JS

Example: name: "Project Report" body: "Status: In ProgressTask 1"

Inputs: name (required), body (required), folder_path. Returns: result

delete_folderA

Delete a folder in Apple Notes by ID with AppleScript verification.

Security Features:

  • Verifies folder exists with the given ID

  • Confirms folder name matches before deletion

  • Uses primary key ID for precise identification

  • AppleScript handles ID and name verification automatically

  • Provides detailed error messages for troubleshooting

Output:

  • Folder name, ID, deletion status and method information

Inputs: folder_id (required), folder_name (required). Returns: result

delete_noteA

Delete a note by its primary key ID with AppleScript verification.

Security Features:

  • Verifies note exists with the given ID

  • Confirms note name matches before deletion

  • Uses primary key ID for precise identification

  • AppleScript handles ID and name verification automatically

  • Provides detailed error messages for troubleshooting

Output:

  • Note name, ID, deletion status and method information

Inputs: note_id (required), note_name (required). Returns: result

list_all_notesA

List all notes across all folders with their names and IDs.

Features:

  • Lists ALL notes from ALL folders in Apple Notes

  • Shows note names, IDs, and folder locations

  • Includes notes from Recently Deleted folder

  • Provides comprehensive system overview

Output Format:

  • Numbered list of all notes

  • Note names with emoji indicators

  • Note IDs for reference

  • Folder location for each note

Returns: Complete list of all notes across all folders in Apple Notes

Inputs: no named parameters. Returns: result

list_folder_with_structureA

List the complete folder structure with hierarchical tree format.

Features:

  • Shows all folders in hierarchical tree format

  • Displays folder nesting levels with visual indicators

  • Works with root level and nested folder structures

Output Format:

  • Tree structure with ├── and └── indicators

  • Clear hierarchy visualization

  • Folder names with proper indentation

Returns: Hierarchical tree structure of all folders in Apple Notes

Inputs: no named parameters. Returns: result

list_notes_with_structureA

List the complete folder structure with notes included in hierarchical tree format.

Features:

  • Shows all folders and notes in hierarchical tree format

  • Displays folder nesting levels with visual indicators

  • Lists notes within each folder

  • Works with root level and nested folder structures

Output Format:

  • Tree structure with ├── and └── indicators

  • Folder names with proper indentation

  • Notes listed under their respective folders

Returns: Hierarchical tree structure of all folders and notes in Apple Notes

Inputs: no named parameters. Returns: result

move_folderA

Move a folder from one location to another in Apple Notes by ID with AppleScript verification.

Features:

  • Moves folders by ID with AppleScript verification

  • Comprehensive validation and duplicate detection

  • Unicode and emoji support for folder names

  • Works with root level and nested paths

Validation:

  • Validates target path exists

  • Prevents duplicate names in target location

  • Enforces 5-level nesting depth limit

  • AppleScript verifies ID and name match the same folder

Inputs: folder_id (required), folder_name (required), target_path. Returns: result

move_noteA

Move a note from one folder to another in Apple Notes by ID with AppleScript verification.

Features:

  • Moves notes between root folders and nested paths (up to 5 levels deep)

  • Comprehensive validation and error handling

  • Supports all folder path types (root, simple, nested)

  • Maintains note content and metadata during move

  • AppleScript verifies ID and name match before moving

Requirements:

  • Note must exist with the given ID and name

  • Target folder path must exist

  • AppleScript handles all verification automatically

Inputs: note_id (required), note_name (required), target_folder_path (required). Returns: result

read_folderA

Read a folder by its primary key ID with AppleScript verification.

Security Features:

  • Verifies folder exists with the given ID and name

  • Uses primary key ID for precise identification

  • Returns detailed folder information with contents

Output:

  • Folder metadata (name, ID, creation/modification dates)

  • Direct child folders (names and IDs)

  • Notes in the folder (names and IDs)

  • Summary counts

Inputs: folder_id (required), folder_name (required). Returns: result

read_noteA

Read a note by its primary key ID with AppleScript verification.

Security Features:

  • Verifies note exists with the given ID and name

  • Uses primary key ID for precise identification

  • Returns full note content with metadata

Output:

  • Note name, ID, folder, creation/modification dates

  • Full note content (title + body)

  • Status and read method information

Inputs: note_id (required), note_name (required). Returns: result

rename_folderA

Rename a folder in Apple Notes by ID with enhanced name verification.

Features:

  • Renames folders by ID with double name verification

  • Comprehensive validation and duplicate detection

  • Unicode and emoji support for folder names

  • Works with root level and nested paths

Validation:

  • Max 128 characters, no special chars: < > : " | ? *

  • Prevents duplicate names in same location

  • New name cannot be same as current name

  • Verifies folder ID matches current name (double verification)

  • Gets actual folder name by ID for additional security

Inputs: folder_id (required), current_name (required), new_name (required). Returns: result

search_notesA

Search for notes containing the specified keywords.

Features:

  • Searches through all notes in Apple Notes

  • Finds notes containing any of the specified keywords

  • Case-insensitive search in note content

  • Returns note details with matched keywords

Output Format:

  • Numbered list of matching notes

  • Note names, IDs, and folder locations

  • Matched keywords for each note

Inputs: keywords (required). Returns: result

update_noteA

Update an existing note by its primary key ID with AppleScript verification.

Required: note_id, note_name, new_name, and new_body parameters Supported HTML: , , , , , Best Practices: Use semantic HTML, add tags for spacing, avoid CSS styles Security: AppleScript verifies ID and name match before updating

Example: note_id: "p1234" note_name: "Current Note Title" new_name: "Updated Report" new_body: "Status: CompleteDone"

Inputs: note_id (required), note_name (required), new_name (required), new_body (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource (folder or note) with a specific action (create, read, update, delete, list, move, search, rename). The few overlapping listing tools have clearly different output formats (plain list vs. hierarchical structure).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, such as create_folder, list_notes_with_structure, move_note. There are no variations or mixed conventions.

    Tool Count5/5

    14 tools is well-scoped for an Apple Notes management server. It covers all core operations (CRUD, listing, searching, moving, renaming) for both folders and notes without unnecessary bloat or omissions.

    Completeness5/5

    The tool surface provides complete lifecycle management for folders and notes: create, read, update, delete, list, search, move, rename. No obvious missing operations for the domain of note-taking.

    Resources

    Related MCP Connectors

    Related MCP Servers