bear-notes-mcp
vasylenko/bear-notes-mcp加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你有没有过这样的经历——明明记得在某个笔记里写过一段关于某技术的深度分析，但翻遍整个笔记库也找不到？甚至花了十几分钟，结果发现关键词拼错了。这种"明明知道有，但就是找不到"的感觉，对于重度笔记用户来说几乎是家常便饭。
更让人头疼的是，当你想让 AI 助手帮你整理或利用笔记时，往往需要把笔记内容手动粘贴给 AI——复制粘贴费时费力，而且只能处理当前这一篇。但你有没有想过：如果 AI 能直接搜索、阅读、编辑你的整个笔记库呢？
这就是 bear-notes-mcp 要解决的问题。
Bear Notes 是 macOS/iOS 平台上最受欢迎的 Markdown 笔记应用之一，以优雅的界面和强大的标签系统著称。但 Bear 本身是一个纯笔记工具，不具备 AI 能力。2024 年开始，随着 Claude、Cursor、Windsurf 等 AI 工具的普及，一个很自然的想法涌现出来：能不能让 AI 助手直接访问我的 Bear 笔记？
作者 Serhii Vasylenko 就是这样一位用户。他在 2024 年开发了这款非官方的 MCP 服务器，目标是：让任何 MCP 兼容的 AI 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、Codex 等）都能直接查询和操作 Bear 笔记库。
截至目前，该项目已在 GitHub 获得约 200+ stars，被收录于 Glama AI 的 MCP 服务器目录，获得了 Bear 官方社区用户的积极反馈。2025 年 12 月支持独立运行，2026 年持续迭代，最新版本 3.0.1。
bear-notes-mcp 提供了 12 个 MCP 工具，覆盖了笔记操作的完整生命周期：
读取工具（默认开启）：
bear-search-notes：相关性排名搜索，检索标题、正文、OCR 图片文字，支持按标签、日期、置顶状态过滤bear-open-note：通过 ID 或标题精确打开笔记，支持 OCR 图片/PDF 内容提取bear-list-tags：以树形结构列出所有标签及其笔记数量bear-find-untagged-notes：找出没有任何标签的笔记写入工具（需开启「编辑模式」）：
bear-create-note：创建新笔记，支持标题、正文、标签bear-add-text：在笔记特定位置追加文本（标题、正文开头、末尾或指定章节标题下）bear-replace-text：替换笔记内容或指定章节bear-add-file：为笔记附加图片、PDF 等文件（最大 25MB）bear-add-tag / bear-rename-tag / bear-delete-tag：标签管理bear-archive-note：归档笔记
图1：搜索界面截图——相关性排名搜索结果，包含上下文摘要片段
这是项目最有趣的部分。Bear Notes 的数据存储在 macOS 的一个 SQLite 数据库文件中（路径：~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite）。bear-notes-mcp 使用 Node.js 内置的 node:sqlite 模块直接读取这个数据库，无需 Bear 应用本身运行。
搜索功能的实现依赖于 FTS5（Full-Text Search 5）——SQLite 内置的全文搜索引擎。项目在 Bear 数据库基础上构建了一个独立的 FTS 索引表（fts-index.ts），对笔记标题、正文、标签进行分词索引，然后支持布尔查询和相关性排名。
关键设计细节：1. Core Data 时间戳转换：Bear 使用 Core Data 存储时间（以 2001-01-01 为 epoch），项目正确处理了时间戳转换（bear-encoding.ts）
2. 乐观锁机制：每次笔记操作都需要携带 Revision 令牌（对应 Bear 数据库的 Z_OPT 字段），防止并发写入冲突
3. 写入路由：读操作走 SQLite 直查，写操作通过 Bear 的 x-callback-url 协议路由到 Bear 应用处理，确保写入经过 Bear 官方验证
4. 分层工具注册：通过 ENABLE_CONTENT_REPLACEMENT 环境变量控制编辑模式，LLM 只会看到当前模式下可用的工具列表，避免幻觉调用
图2：功能演示 GIF——展示 AI 通过 MCP 调用搜索 Bear 笔记并获取结果
下载 .mcpb 扩展文件 → 双击 → Claude Desktop 弹出安装确认 → 完成。安装后直接对 Claude 说"帮我搜索关于 XXX 的笔记"即可。
# Claude Code
claude mcp add -s user bear-notes -- npx -y bear-notes-mcp@latest
# 通用配置（Cursor, Codex, Windsurf 等）
{
"mcpServers": {
"bear-notes": {
"command": "npx",
"args": ["-y", "bear-notes-mcp@latest"]
}
}
}
硬性要求：macOS + Bear Notes 应用已安装并至少打开过一次。这是项目最大的局限——它根本无法在 Linux 或 Windows 上运行，所有本地化设计都围绕 macOS 展开。
最大的局限：平台锁定。 这不是一个可以部署到服务器的 Web 应用，而是深度绑定 macOS 的桌面工具。如果你是 iPad 用户或 Linux/Windows 用户，这个项目对你完全没用。
数据安全问题。 bear-notes-mcp 读取 Bear 的原始 SQLite 数据库文件，这意味着任何能访问这个数据库的人都可以读取你的所有笔记（包括已删除但未清空的笔记）。好在项目本身是离线设计——不发送任何网络请求，不存在服务器端数据泄露风险。
与官方 Bear MCP 的关系。 这是一个非官方项目，Bear 官方在 2026 年 5 月发布了 Bear 2.8 Beta，开始内置 Claude Connector 和官方 MCP 支持。虽然这让 bear-notes-mcp 面临竞争，但也说明这个方向是正确的——官方看到了 MCP 集成笔记的价值。
Edit Mode 的权衡。 默认只开启读取工具，通过环境变量开启写入能力。这是一个安全设计，但也意味着想要体验完整功能的用户需要折腾配置，对非技术用户不够友好。
bear-notes-mcp 代表了一个重要趋势：将本地个人数据作为 AI 的"外部记忆"。传统 RAG（检索增强生成）需要将数据上传到云端，而 bear-notes-mcp 的方案是纯本地的——所有数据处理在 macOS 本地完成，AI 只能看到用户明确授权的内容，不存在云端数据泄露风险。
这种「隐私优先的本地 RAG」模式，对于处理敏感笔记、工作文档、私人日记等场景具有重要参考价值。随着 AI 助手和本地模型能力的提升，这类「本地知识库 + AI」的工具可能会成为继浏览器插件之后的下一个爆发点。
项目地址：https://github.com/vasylenko/bear-notes-mcp | 作者：Serhii Vasylenko | License: Apache-2.0