bear-mcp

bear-mcp

一个 MCP 服务，可让 AI 助手（Claude 等）完整访问你在 macOS 上的 Bear 笔记。搜索、阅读、创建、编辑和锁定笔记——全程通过 AI 工作流完成。

为什么？

Bear 没有官方 API。本项目通过两种方式弥补这一缺口：

• 读取直接访问 Bear 的 SQLite 数据库——速度快、无提示，即使 Bear 已关闭也能使用。
• 写入使用 Bear 的 x-callback-url 方案——每次操作都会短暂打开 Bear，但可靠且不会破坏数据。
• 锁定/解锁使用 AppleScript UI 自动化——这是唯一的方法，因为 Bear 没有在其 URL 方案中提供此功能。

它能做什么？

工具	功能
bear_search	按文本和/或标签查找笔记
bear_get	读取笔记的完整内容
bear_recent	列出最近修改的笔记
bear_tags	列出所有标签
bear_create	创建新笔记
bear_prepend	在笔记顶部添加文本
bear_append	在笔记底部添加文本
bear_replace	替换笔记的全部正文
bear_trash	将笔记移至废纸篓
bear_lock	切换只读状态（锁定/解锁）

笔记通过 UUID（或 UUID 的前 8 个字符）而非标题进行标识。

设置

1. 安装

git clone https://github.com/zmainen/bear-mcp.git
cd bear-mcp
pip install -e .

2. 添加到 MCP 配置

在项目的 .mcp.json（或同等配置文件）中：

{
  "bear-notes": {
    "command": "python",
    "args": ["/path/to/bear-mcp/mcp_server.py"]
  }
}

3. 授予辅助功能权限（仅用于锁定）

bear_lock 使用 AppleScript 点击 Bear 的菜单项。macOS 首次会提示你授予辅助功能权限。这是一次性设置，位置在系统设置 > 隐私与安全性 > 辅助功能。

使用场景

AI 辅助记笔记。 让 AI 助手将想法、会议记录或研究内容连同适当的标签直接记录到 Bear 中。

自动添加标签。 Bear 的 add-tags URL 操作无法正常工作。本服务通过在笔记正文中写入行内 #tags 来绕过此问题，Bear 会自动识别这些标签。嵌套标签（如 #project/docs）也适用。

搜索和总结。 让 AI 帮你查找并整合笔记中的信息——它可以按文本搜索、按标签筛选并读取完整内容。

锁定已完成的工作。 使用 bear_lock 在审阅后将笔记设为只读，防止意外修改。

库的用法

底层 Python 库可以独立于 MCP 使用：

from bear_app import BearNotesAPI

bear = BearNotesAPI()  # auto-detects Bear's database

notes = bear.search_notes("query", tag="project")
note = bear.get_note(note_id="83779062-...")
print(note.title, note.is_locked, note.locked_date)

bear.create_note(title="New note", text="body", tags=["project"])
bear.toggle_read_only(note_id=uuid)

注意事项

• ID 是 UUID，不是行号。Bear 内部使用 ZUNIQUEIDENTIFIER。
• Bear 的 URL 方案中，add-tags 无法正常工作。请改用行内 #tag 文本。
• 空格必须写为 %20，不能写成 +。Bear 会将 + 按字面解释。该库会自动处理。
• 锁定需要 Bear 正在运行，并且需要辅助功能权限。其底层采用 UI 自动化——可靠，但无法隐形运行。
• 切勿写入 SQLite 数据库。 所有写入操作都通过 Bear 的 URL 方案完成。

许可证

MIT — Zach Mainen，2025