Apple Notes Mcp

apple-notes-mcp

Apple Notes 的 MCP 服务，支持语义搜索和 CRUD 操作。Claude 可通过自然语言搜索、读取、创建、更新和管理你的 Apple Notes。

功能

• 基于分块的搜索 - 将长笔记拆分成多个块，以实现精准匹配
• 查询缓存 - 重复搜索速度提升 60 倍
• 知识图谱 - 发现标签、链接和相关笔记
• 混合搜索 - 结合向量搜索与关键词搜索，并使用倒数排名融合
• 语义搜索 - 按含义而非关键词查找笔记
• 完整 CRUD - 创建、读取、更新、删除和移动笔记
• 增量索引 - 仅重新嵌入有更改的笔记
• 后台索引任务 - 异步执行完整/增量索引，并支持轮询进度
• 双重嵌入方式 - 使用本地 HuggingFace 或 OpenRouter API

1.9.0 新增内容

• 大型资料库索引 - Fetch 以批量方式读取笔记属性，因此索引数千条笔记也能顺利完成，不再卡住
• 更可靠的 Fetch - 按批次重试被锁定或正在同步的笔记，并跳过这些笔记并生成报告，而不是让整个任务失败
• 可取消读取 - 长时间运行的 Notes 读取会超时（JXA_TIMEOUT_MS），且取消操作会真正停止 Fetch

1.8.1 新增内容

• 更快的 list-notes 文件夹筛选 - list-notes 现在只查询指定文件夹，而不是先扫描所有笔记
• 正确处理同名文件夹 - 文件夹筛选现在会汇总各个账户中的匹配文件夹
• 大型资料库性能优化 - 在大型笔记库中，按文件夹列出笔记的速度显著提升

安装

npm（推荐）

npm install -g @disco_trooper/apple-notes-mcp
apple-notes-mcp

设置向导将引导你完成以下步骤：

1. 选择嵌入提供方（本地或 OpenRouter）
2. 根据需要配置 API 密钥
3. 设置 Claude Code 集成
4. 为笔记建立索引

从源代码安装

git clone https://github.com/disco-trooper/apple-notes-mcp.git
cd apple-notes-mcp
bun install
bun run start

要求

• macOS（通过 JXA 使用 Apple Notes）
• Bun 运行时
• 安装了笔记的 Apple Notes 应用

快速开始

安装后运行该命令：

apple-notes-mcp

首次运行时会自动启动设置向导。设置完成后，重启 Claude Code 即可使用 MCP 工具。

配置

配置文件存储在 ~/.apple-notes-mcp/.env 中：

变量	描述	默认值
OPENROUTER_API_KEY	OpenRouter API 密钥（启用云端嵌入）	-
EMBEDDING_MODEL	模型名称（本地或 OpenRouter）	Xenova/multilingual-e5-small
EMBEDDING_DIMS	嵌入维度	4096
READONLY_MODE	禁止所有写入操作	false
INDEX_TTL	搜索时自动刷新的间隔（秒；未设置时禁用）	-
SEARCH_REFRESH_TIMEOUT_MS	搜索等待刷新后再使用过期索引的最长时间	2000
INDEX_JOB_RETENTION_SECONDS	已完成/失败的索引任务可供查询的时长	3600
EMBEDDING_BATCH_SIZE	生成嵌入时的批次大小	50
NOTES_FETCH_BATCH_SIZE	Fetch Notes 时的批次大小	100
JXA_TIMEOUT_MS	单次 Notes 读取的最长时间（毫秒）	120000
DEBUG	启用调试日志	false

搜索自动刷新策略

• search-notes 不会在每次请求时强制刷新。
• 如果未设置 INDEX_TTL，则禁用自动刷新，搜索使用当前索引。
• 如果设置了 INDEX_TTL，则仅在 TTL 过期后刷新。
• 如果刷新失败或耗时超过 SEARCH_REFRESH_TIMEOUT_MS，搜索会改用过期索引的结果，而不会超时。

重新配置：

apple-notes-mcp setup
# or from source:
bun run setup

嵌入提供方

本地（默认）：使用 HuggingFace Transformers 和 Xenova/multilingual-e5-small。免费，可在本地运行，下载大小约为 200 MB。

OpenRouter：使用云 API。速度快，无需本地资源，但需要从 openrouter.ai 获取 API 密钥。

模型对比请参阅 docs/models.md。

工具

搜索与发现

search-notes

混合向量与全文搜索。

query: "meeting notes from last week"
folder: "Work"           # optional, filter by folder
limit: 10                # default: 20
mode: "hybrid"           # hybrid, keyword, or semantic
include_content: false   # include full content vs preview

list-notes

按排序和筛选条件列出笔记。不带参数时，显示索引统计信息。

sort_by: "modified"      # created, modified, or title (default: modified)
order: "desc"            # asc or desc (default: desc)
limit: 10                # max notes to return (1-100)
folder: "Work"           # filter by folder (case-insensitive)

提供 folder 时，服务只会从 Apple Notes 获取匹配文件夹中的笔记。即使你的笔记库中有数百条笔记，这也能让限定文件夹的请求保持快速。

示例：

• 获取最新的 5 条笔记：{ sort_by: "created", order: "desc", limit: 5 }
• 最近修改的笔记：{ sort_by: "modified", limit: 10 }
• 按字母顺序列出文件夹中的笔记：{ sort_by: "title", order: "asc", folder: "Projects" }

list-folders

列出所有 Apple Notes 文件夹。

get-note

按标题获取笔记内容。

title: "My Note"          # or "Work/My Note" for disambiguation
include_html: false       # include raw HTML (default: false)

get-tables

从笔记中提取结构化表格数据。

title: "My Note"

返回：

{
  "tableCount": 2,
  "tables": [{
    "index": 0,
    "rows": [["Header1", "Header2"], ["Val1", "Val2"]],
    "formatting": [[{"bold": true}, {"bold": true}], ...]
  }]
}

索引

index-notes

为语义搜索建立笔记索引。

mode: "incremental"       # incremental (default) or full
force: false              # force reindex even if TTL hasn't expired
background: false         # optional; defaults to false (synchronous mode)

使用 mode: "full" 创建分块索引，以提升对长笔记的搜索效果。首次建立完整索引需要更长时间，因为要生成分块，但之后的搜索会很快。

对于大型笔记库，建议在后台建立索引：

start-index-job

mode: "full"               # full or incremental

返回包含 id、status 和 progress 的任务快照。 在获取、嵌入和持久化阶段，进度会分成较小步幅更新。

get-index-job

job_id: "<job-id>"

轮询，直到状态变为 completed、failed 或 cancelled。 你可能会看到作为过渡状态的 cancelling。

list-index-jobs

limit: 10                  # optional, 1-50

cancel-index-job

job_id: "<job-id>"

请求尽力取消正在运行的任务。取消采用协作方式：

• 长时间运行的步骤必须到达取消检查点。
• 可能会保留部分已完成的工作。
• 当前任务达到 cancelled 后，再启动新任务。

reindex-note

手动编辑后重新索引单条笔记。

title: "My Note"

CRUD 操作

create-note

在 Apple Notes 中创建笔记。

title: "New Note"
content: "# Heading\n\nMarkdown content..."
folder: "Work"            # optional, defaults to Notes

创建、更新、删除或移动笔记后，服务会尽力自动同步向量索引和分块索引。 如果同步部分失败，工具响应会包含 index sync warning。运行 reindex-note 或 index-notes。

update-note

更新现有笔记。

title: "My Note"
content: "Updated markdown content..."
reindex: true             # re-embed after update (default: true)

delete-note

删除笔记（需要确认）。

title: "My Note"
confirm: true             # must be true to delete

move-note

将笔记移动到其他文件夹。

title: "My Note"
folder: "Archive"

batch-delete

一次删除多条笔记。

titles: ["Note 1", "Note 2"]  # OR folder: "Old Project"
confirm: true                 # required for safety

batch-move

将多条笔记移动到目标文件夹。

titles: ["Note 1", "Note 2"]  # OR sourceFolder: "Old"
targetFolder: "Archive"       # required

索引管理

purge-index

清除所有已索引的数据。在切换嵌入模型或修复损坏的索引时使用。

confirm: true   # required for safety

清除后，运行 index-notes 以重建索引。

知识图谱

list-tags

列出所有标签及其出现次数。

search-by-tag

查找带有指定标签的笔记。

tag: "project"
folder: "Work"    # optional
limit: 20         # default: 20

related-notes

查找与源笔记相关的笔记。

title: "My Note"
types: ["tag", "link", "similar"]  # default: all
limit: 10                          # default: 10

export-graph

导出知识图谱以供可视化。

format: "json"     # json or graphml
folder: "Work"     # optional filter

支持的格式：

• json - 用于自定义可视化（D3.js、Web 应用）
• graphml - 用于专业工具（Gephi、yEd、Cytoscape）

Claude Code 设置

自动设置（推荐）

设置向导会自动将 apple-notes-mcp 添加到 Claude Code。安装后运行 apple-notes-mcp。

手动配置

添加到 ~/.claude.json：

使用 npm 安装：

{
  "mcpServers": {
    "apple-notes": {
      "command": "apple-notes-mcp",
      "args": [],
      "env": {}
    }
  }
}

从源代码安装：

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"],
      "env": {}
    }
  }
}

使用示例

完成设置后，使用自然语言与 Claude 交互：

• “搜索我的笔记，查找项目创意”
• “在 Work 文件夹中创建一条名为‘Meeting Notes’的笔记”
• “我的假期计划笔记里写了什么？”
• “将‘Old Project’笔记移到 Archive”
• “为我的笔记编制索引”（在 Apple Notes 中添加笔记后）

故障排除

“Note not found”

当多个笔记同名时，请使用完整路径格式 Folder/Note Title。

首次搜索速度较慢

首次使用时，本地嵌入模型会下载模型（约 200MB）。后续搜索速度会很快。

“READONLY_MODE is enabled”

在 .env 中设置 READONLY_MODE=false，以启用写入操作。

搜索结果中缺少笔记

运行 index-notes 以更新搜索索引。如果增量索引漏掉了更改，请使用 mode: full。

“iCloud account not available” / Can't get account "iCloud"

此错误来自另一种 Apple Notes MCP 实现，该实现使用工具 search_notes 和参数 Keywords。

本项目使用：

• 工具：search-notes
• 参数：query

如果客户端使用 Keywords 调用 search_notes，请将 MCP 配置指向 apple-notes-mcp，然后重启客户端。

JXA 错误

确保 Apple Notes 正在运行且包含笔记。出现提示时，请授予自动化权限。

“JSON Parse error: Unexpected identifier undefined”

这通常表示索引进程内存不足。请尝试：

1. 关闭其他应用程序以释放内存
2. 在 .env 中设置 EMBEDDING_BATCH_SIZE=25，以减少内存用量
3. 重启 Apple Notes 应用
4. 再次运行 index-notes

编制索引时跳过的笔记

以下情况可能会导致某些笔记被跳过：

• 已锁定——如果希望将其编入索引，请在 Apple Notes 中解锁
• 正在同步——等待 iCloud 同步完成，然后重新编制索引
• 已损坏——尝试将内容复制到新笔记中，然后删除旧笔记

索引器会报告被跳过的笔记，并继续处理其余笔记。

开发

# Type check
bun run check

# Run tests
bun run test

# Run with coverage
bun run test:coverage

# Run with debug logging
DEBUG=true bun run start

# Watch mode
bun run dev

贡献

欢迎提交 PR！请：

• 提交前运行 bun run check
• 为新功能添加测试
• 根据需要更新文档

许可证

MIT