Apple Notes MCP Server

1# Apple Notes MCP Server
2 
3> Powerful tools for automating Apple Notes using Model Context Protocol (MCP)
4 
5**mcp-name: io.github.henilcalagiya/mcp-apple-notes**
6 
7[![PyPI version](https://badge.fury.io/py/mcp-apple-notes.svg)](https://pypi.org/project/mcp-apple-notes/)
8[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
10 
11## Overview
12 
13Apple 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.
14 
15## Features
16 
17* **Full CRUD support** for Apple Notes (Create, Read, Update, Delete)
18* **Works with Continue.dev, Claude Desktop, Perplexity, and other MCP clients**
19* **Native AppleScript integration** for reliable macOS automation
20* **Comprehensive tools** for Apple Notes automation
21* **Automatic installation** via `uvx` or manual setup
22* **FastMCP implementation** with modern decorator-based API
23 
24## Requirements
25 
26* **macOS** - Required for AppleScript support
27* **Python 3.10+** - Required for MCP SDK compatibility
28* **Apple Notes application** - Must be installed and accessible
29* **MCP-compatible client** (e.g., Continue.dev, Claude Desktop)
30 
31## Quick Start
32 
33### Step 1: Install uv (if not already installed)
34 
35**macOS/Linux:**
36```bash
37curl -LsSf https://astral.sh/uv/install.sh | sh
38```
39 
40**Windows (PowerShell):**
41```powershell
42powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
43```
44 
45**Alternative (pip):**
46```bash
47pip install uv
48```
49 
50### Step 2: Add MCP Configuration
51 
52Add this configuration to your MCP client:
53 
54**For Perplexity, Cursor, Continue.dev, Claude Desktop:**
55```json
56{
57  "mcpServers": {
58    "apple-notes": {
59      "command": "uvx",
60      "args": ["mcp-apple-notes@latest"]
61    }
62  }
63}
64```
65 
66**🎉 That's it!** Your MCP client will automatically install and run the package when needed.
67 
68> **Note:** Ensure your MCP client has permission to access Apple Notes and execute AppleScript commands in System Preferences → Security & Privacy → Privacy → Accessibility.
69 
70## Available Tools
71 
72### **Note Management (6 tools)**
73- `create_note` - Create notes with HTML content
74- `read_note` - Read notes by ID with verification
75- `update_note` - Update notes by ID with HTML content
76- `delete_note` - Delete notes by ID with verification
77- `move_note` - Move notes between folders
78- `list_all_notes` - List all notes across all folders
79 
80### **Folder Management (5 tools)**
81- `create_folder` - Create folders with path support
82- `read_folder` - Read folder details by ID
83- `rename_folder` - Rename folders by ID
84- `delete_folder` - Delete folders by ID
85- `move_folder` - Move folders between locations
86 
87### **Search & Structure (3 tools)**
88- `search_notes` - Search notes by keywords
89- `list_folder_with_structure` - Show folder hierarchy
90- `list_notes_with_structure` - Show folders + notes hierarchy
91 
92 
93 
94## Content Support
95 
96**HTML Formatting**: `<h1-h6>`, `<b><i><u>`, `<p><div><br>`, `<ul><ol><li>`, `<table>`, `<a>`
97 
98**Special Features**:
99- Unicode and emoji support (🚀, ✅, 📝)
100- Nested folder paths (up to 5 levels)
101- Automatic character escaping
102- Rich content with headers, lists, tables
103 
104## Architecture
105 
106The server follows the MCP protocol specification and is built with a modular architecture:
107 
108- **AppleScript Layer** - Handles direct interaction with Apple Notes
109- **Tools Layer** - Wraps AppleScript operations for MCP tools
110- **FastMCP Server Layer** - Implements MCP protocol using decorators
111 
112## Troubleshooting
113 
114### Common Issues
115 
1161. **"No module named 'mcp'" Error**
117   - Use `uvx` for automatic installation
118   - Ensure `uv` is installed and in PATH
119 
1202. **AppleScript Permission Denied**
121   - Grant permission to your terminal/MCP client in System Preferences → Security & Privacy → Privacy → Accessibility
122 
1233. **Notes Not Found**
124   - Ensure Apple Notes app is installed and accessible
125   - Check that notes exist in the default location
126 
127## License
128 
129This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
130 
131## Author
132 
133**Henil C Alagiya**
134 
135* **GitHub**: [@henilcalagiya](https://github.com/henilcalagiya)
136* **LinkedIn**: [Henil C Alagiya](https://linkedin.com/in/henilcalagiya)
137 
138**Support & Contributions:**
139 
140* 🐛 **Report Issues**: [GitHub Issues](https://github.com/henilcalagiya/mcp-apple-notes/issues)
141* 💬 **Questions**: Reach out on [LinkedIn](https://linkedin.com/in/henilcalagiya)
142* 🤝 **Contributions**: Pull requests welcome!
143