mcp-apple-notes

Apple Notes MCP 服务

使用 Model Context Protocol（MCP）自动化 Apple Notes 的强大工具

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

概述

Apple Notes MCP 服务可将 Apple Notes 与任何兼容 MCP 的客户端无缝集成。通过简单、安全的 AppleScript API 层，该服务可全面自动化笔记操作，包括创建、读取、更新和删除笔记。

功能

• 全面支持 CRUD，适用于 Apple Notes（创建、读取、更新、删除）
• 兼容 Continue.dev、Claude Desktop、Perplexity 及其他 MCP 客户端
• 原生 AppleScript 集成，实现可靠的 macOS 自动化
• 提供全面的工具，用于自动化 Apple Notes
• 支持通过 uvx 自动安装或手动设置
• 采用 FastMCP 实现，提供现代化的基于装饰器的 API

要求

• macOS - AppleScript 支持所必需
• Python 3.10+ - 兼容 MCP SDK 所必需
• Apple Notes 应用 - 必须已安装且可访问
• 兼容 MCP 的客户端（例如 Continue.dev、Claude Desktop）

快速入门

步骤 1：安装 uv（如果尚未安装）

macOS/Linux：

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

Windows (PowerShell)：

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

替代方式（pip）：

pip install uv

步骤 2：添加 MCP 配置

将此配置添加到你的 MCP 客户端：

适用于 Perplexity、Cursor、Continue.dev、Claude Desktop：

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

🎉 就是这么简单！ MCP 客户端会在需要时自动安装并运行此软件包。

注意： 请确保 MCP 客户端已获得访问 Apple Notes 和执行 AppleScript 命令的权限。请前往“系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能”进行设置。

可用工具

笔记管理（6 个工具）

• create_note - 使用 HTML 内容创建笔记
• read_note - 按 ID 读取笔记并进行验证
• update_note - 按 ID 使用 HTML 内容更新笔记
• delete_note - 按 ID 删除笔记并进行验证
• move_note - 在文件夹之间移动笔记
• list_all_notes - 列出所有文件夹中的笔记

文件夹管理（5 个工具）

• create_folder - 创建文件夹，支持路径
• read_folder - 按 ID 读取文件夹详情
• rename_folder - 按 ID 重命名文件夹
• delete_folder - 按 ID 删除文件夹
• move_folder - 在不同位置之间移动文件夹

搜索与结构（3 个工具）

• search_notes - 按关键词搜索笔记
• list_folder_with_structure - 显示文件夹层级结构
• list_notes_with_structure - 显示文件夹与笔记的层级结构

内容支持

HTML 格式：<h1-h6>、<b><i><u>、<p><div><br>、<ul><ol><li>、<table>、<a>

特色功能：

• 支持 Unicode 和表情符号（🚀、✅、📝）
• 支持嵌套文件夹路径（最多 5 层）
• 自动转义字符
• 支持包含标题、列表和表格的富文本内容

架构

此服务遵循 MCP 协议规范，并采用模块化架构构建：

• AppleScript 层 - 负责与 Apple Notes 直接交互
• 工具层 - 将 AppleScript 操作封装为 MCP 工具
• FastMCP 服务层 - 使用装饰器实现 MCP 协议

故障排除

常见问题

1. “No module named 'mcp'”错误

   • 使用 uvx 自动安装
   • 确保已安装 uv 并且其位于 PATH 中

2. AppleScript 权限被拒绝

   • 在“系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能”中，向终端或 MCP 客户端授予权限

3. 找不到笔记

   • 确保 Apple Notes 应用已安装且可访问
   • 检查默认位置中是否存在笔记

许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

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!