用途

apple-notes-mcp 是一个面向 Apple Notes 的 MCP 服务器。它让 Claude 等兼容 MCP 的客户端能够通过自然语言搜索、读取、创建、更新、删除和管理 Apple Notes 中的笔记。

主要能力

语义搜索：按含义而非关键词查找笔记。
混合搜索：结合向量与全文关键词搜索，使用 Reciprocal Rank Fusion 排序。
分块搜索：将长笔记拆分为块以提升匹配准确性。
查询缓存：重复搜索速度提升约 60 倍。
知识图谱：支持标签、链接及相关笔记发现，并可导出为 json 或 graphml 格式用于可视化工具（如 D3.js、Gephi、yEd、Cytoscape）。
完整 CRUD：创建、读取、更新、删除和移动笔记，支持批量删除与批量移动。
增量索引：仅对变更的笔记重新嵌入。
后台索引任务：支持异步全量或增量索引，并提供进度轮询。
双嵌入方式：本地 HuggingFace 或 OpenRouter API。

使用方式

安装与配置

推荐通过 npm 安装。安装后运行命令，首次运行会自动启动设置向导，引导选择嵌入提供商（本地或 OpenRouter）、配置 API 密钥、设置 Claude Code 集成并索引笔记。配置存储在 ~/.apple-notes-mcp/.env。设置完成后需重启 Claude Code 才能使用 MCP 工具。

环境要求

macOS（通过 JXA 使用 Apple Notes）
Apple Notes 应用且包含笔记
需在提示时授予自动化权限

搜索自动刷新策略

search-notes 不会在每次请求时强制刷新：若未设置 INDEX_TTL，自动刷新禁用，搜索使用当前索引；若设置了 INDEX_TTL，仅在超过 TTL 后刷新；若刷新失败或超过 SEARCH_REFRESH_TIMEOUT_MS，搜索回退到陈旧索引结果而非超时。

嵌入提供商

本地（默认）：使用 HuggingFace Transformers 与 Xenova/multilingual-e5-small，免费、本地运行，约 200MB 下载。
OpenRouter：云端 API，速度快、无需本地资源，需要来自 openrouter.ai 的 API 密钥。

搜索与发现

混合向量+全文搜索。
列出笔记，支持排序和过滤；无参数时显示索引统计。
当提供 folder 时，服务器仅从 Apple Notes 获取匹配的文件夹，提升大库中的文件夹范围请求速度。
示例：获取 5 条最新笔记 { sort_by: "created", order: "desc", limit: 5 }；最近修改 { sort_by: "modified", limit: 10 }；按字母顺序 { sort_by: "title", order: "asc", folder: "Projects" }。
列出所有 Apple Notes 文件夹。
按标题获取笔记内容。
从笔记中提取结构化表格数据。
为语义搜索索引笔记：使用 mode: "full" 创建分块索引以改善长笔记搜索，首次全量索引较慢，后续搜索很快。
对于大库，建议使用后台索引，返回包含 id、status、progress 的任务快照，可在 fetch、embed、persist 阶段看到进度；轮询直到状态为 completed、failed 或 cancelled，可能看到 cancelling 过渡状态。取消是合作式的：长步骤需到达取消检查点，可能保留部分工作，需在当前任务达到 cancelled 后再启动新任务。
手动编辑后可重新索引单条笔记。

CRUD 操作

create-note 在 Apple Notes 中创建笔记；创建、更新、删除或移动后，服务器尽力自动同步向量和分块索引，若部分同步失败，工具响应会包含索引同步警告，此时可运行 reindex-note 或 index-notes。update-note 更新现有笔记；delete-note 删除笔记（需要确认）；move-note 移动笔记到其他文件夹；支持批量删除和批量移动。

索引管理

purge-index 清除所有索引数据，用于切换嵌入模型或修复损坏索引；清除后运行 index-notes 重建。

知识图谱

列出所有标签及出现次数。
查找具有特定标签的笔记。
查找与源笔记相关的笔记。
导出知识图谱用于可视化，支持 json（自定义可视化，如 D3.js、Web 应用）和 graphml（专业工具，如 Gephi、yEd、Cytoscape）。

Claude Code 设置

推荐自动方式：设置向导会自动将 apple-notes-mcp 添加到 Claude Code。安装后运行 apple-notes-mcp。也可手动添加到 ~/.claude.json，npm 安装和源码安装的配置不同。设置后可用自然语言让 Claude 操作，例如“Search my notes for project ideas”“Create a note called 'Meeting Notes' in the Work folder”“What's in my note about vacation plans?”“Move the 'Old Project' note to Archive”“Index my notes”（在 Apple Notes 添加笔记后）。

适用场景

适用于 macOS 用户希望借助 Claude 等 MCP 客户端，通过自然语言高效检索和管理大量 Apple Notes 笔记的场景，尤其适合需要语义搜索、知识图谱发现、批量操作或大笔记库索引的用户。

限制

仅支持 macOS，依赖 Apple Notes 应用。
需要授予自动化权限。
写入操作需在 .env 中设置 READONLY_MODE=false。
大型库索引可能遇到内存问题，可通过设置 EMBEDDING_BATCH_SIZE=25 等缓解。
锁定、同步中或损坏的笔记可能被跳过，需相应处理后再索引。
取消后台任务为合作式，可能保留部分工作。
本地嵌入首次使用需下载约 200MB 模型。
若客户端调用的是 search_notes 且参数为 Keywords，则可能指向其他实现，需将 MCP 配置指向 apple-notes-mcp 并重启客户端。

版本更新要点

1.9.0：大库索引时批量读取笔记属性，避免数千笔记索引停滞；对锁定或同步中的笔记按批次重试并跳过报告；长笔记读取超时（JXA_TIMEOUT_MS）且取消可实际停止获取。
1.8.1：list-notes 的文件夹过滤仅查询请求的文件夹而非扫描全部笔记；修复重复文件夹名正确性，跨账户聚合匹配文件夹；大库性能显著提升。

apple-notes-mcp

工具介绍

用途