使用说明

Bear MCP服务器

A. 模型上下文协议服务器熊 --苹果设备上的笔记应用程序。为AI助手（Claude Code、Claude Desktop等）提供对Bear笔记的完全读/写访问权限。

为什么

Bear没有官方的API，但它确实有：

一 x-callback-url方案 用于创建和修改注释
A. SQLite数据库 这对于查询笔记来说是可读的

该服务器结合了这两者：SQLite用于快速、灵活的读取；x-callback-url用于通过Bear自己的同步引擎进行安全写入。

建筑

┌─────────────┐    stdio (JSON-RPC)    ┌──────────────────┐
│  MCP Client │◄──────────────────────►│  Bear MCP Server │
│  (Claude)   │                        │  (Python)        │
└─────────────┘                        └────────┬─────────┘
                                                │
                                    ┌───────────┴───────────┐
                                    │                       │
                                    ▼                       ▼
                              ┌──────────┐         ┌──────────────┐
                              │  SQLite  │         │  x-callback  │
                              │  (ro)    │         │  (open -g)   │
                              └────┬─────┘         └──────┬───────┘
                                   │                      │
                                   ▼                      ▼
                              ┌────────────────────────────────┐
                              │           Bear.app             │
                              │     (iCloud sync, storage)     │
                              └────────────────────────────────┘

读取直接转到Bear的SQLite数据库(file:...?mode=ro).这是安全的——我们是一个只读的消费者，Bear将数据库视为自己的数据库。

写通过Bear的x-callback-url方案(bear://x-callback-url/...)，通过Bear自己的API层进行路由。这确保了iCloud同步、冲突解决和数据完整性都由Bear自己处理。

所有写入操作都使用 open -g 背景 show_window=no + open_note=no 安静地奔跑，不转移注意力。

需求

macOS（Bear仅适用于苹果；SQLite路径和 open 命令是特定于macOS的）
熊安装
Python 3.10+
mcp Python包(pip install mcp)

安装

克劳德代码

添加 ~/.claude.json:

{
  "mcpServers": {
    "bear": {
      "command": "python3",
      "args": ["/path/to/bear/server.py"]
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bear": {
      "command": "python3",
      "args": ["/path/to/bear/server.py"]
    }
  }
}

其他MCP客户端

服务器使用stdio传输。将其作为子流程启动：

python3 server.py

工具（15）

读取工具（通过SQLite）

`bear_search`

按文本内容或标签搜索笔记。

参数	类型	默认值	说明
`term`	string	null	搜索字符串（匹配标题和正文）
`tag`	string	null	按标签筛选（例如“工作”或“工作/项目”）
`limit`	int	20	最大结果

返回：注释标题、id、创建/修改日期和文本预览。

`bear_read_note`

阅读笔记的全部内容。

参数	类型	默认值	说明
`title`	string	null	注释标题（部分匹配）
`id`	string	null	注意唯一标识符（完全匹配，优先）

返回：包含元数据（id、日期、固定、存档状态）的完整笔记内容。

`bear_list_tags`

列出所有标签。

参数	类型	默认值	说明
`limit`	int	50	最大结果

`bear_list_todos`

使用todo复选框查找笔记。

参数	类型	默认值	说明
`show_completed`	bool	false	包括所有待办事项完成的注释
`limit`	int	20	最大结果

返回：注释标题、id、已完成和剩余待办事项的计数。

编写工具（通过x-callback-url）

`bear_create_note`

创建新笔记。

参数	类型	默认值	说明
`title`	string	必填	注释标题
`text`	string	null	正文内容（markdown）
`tags`	string	null	逗号分隔的标签
`timestamp`	bool	false	预置当前日期/时间

`bear_append_to_note`

向现有注释添加文本。

参数	类型	默认值	说明
`text`	string	必填	要添加的文本
`title`	string	null	注释标题
`id`	string	null	注释标识符
`mode`	string	“append”	“appent”或“prepend”
`header`	string	null	针对特定对象 `## Header`
`timestamp`	bool	false	预置当前日期/时间

`bear_update_section`

替换特定标题下的内容。

参数	类型	默认值	说明
`text`	string	必填	新建节内容
`header`	string	必需	目标标头名称
`title`	string	null	注释标题
`id`	string	null	注释标识符

这是最强大的书写工具——它可以在不接触其他部分的情况下对笔记的特定部分进行手术更新。

`bear_add_tags`

在笔记中添加标签。

参数	类型	默认值	说明
`tags`	string	必填	逗号分隔的标签
`title`	string	null	注释标题
`id`	string	null	注释标识符

`bear_rename_tag`

重命名所有笔记中的标记。

参数	类型	默认值	说明
`name`	string	必填	当前标记名称
`new_name`	string	必填	新标记名称

`bear_delete_tag`

删除标签（笔记保留，只是未标记）。

参数	类型	默认值	说明
`name`	string	必填	要删除的标记

`bear_trash_note`

把一张纸条移到垃圾桶里。

参数	类型	默认值	说明
`title`	string	null	注释标题
`id`	string	null	注释标识符

`bear_archive_note`

将笔记存档。

参数	类型	默认值	说明
`title`	string	null	注释标题
`id`	string	null	注释标识符

`bear_grab_url`

将网页另存为熊笔记。Bear处理HTML到markdown的转换。

参数	类型	默认值	说明
`url`	string	必需	要保存的Web URL
`tags`	string	null	逗号分隔的标签
`pin`	bool	false	固定到顶部

`bear_add_file`

将文件（图像、屏幕截图、PDF）附加到注释中。

参数	类型	默认值	说明
`file_path`	string	必需	文件的绝对路径
`title`	string	null	注释标题
`id`	string	null	注释标识符
`header`	string	null	在特定标题下插入
`mode`	string	“append”	“appent”或“prepend”

文件大小限制： 约750KB。文件采用base64编码，通过URL方案发送，实际限制在1MB左右。对于较大的图像，请先压缩或调整大小。

`bear_create_from_template`

从模板注释创建新注释。

参数	类型	默认值	说明
`template_title`	string	必填	模板注释的标题
`new_title`	string	必填	新注释的标题
`replacements`	string	null	管道分隔 `key=value` 配对（例如。 `{{date}}=2026-03-06\|{{project}}=Trixie`)
`tags`	string	null	新注释的标签

模板是基于惯例的——任何注释都可以是模板。该工具读取注释，剥离其标题和尾随标签，应用占位符替换，并创建新注释。

运作原理

SQLite数据库

Bear将所有笔记存储在Core Data SQLite数据库中：

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

关键表格：

ZSFNOTE --所有注释（标题、文本、日期、标志）
ZSFNOTETAG --标签定义
Z_5TAGS --将表格链接到标签

时间戳使用 核心数据时代 （自2001-01-01 00:00:00 UTC以来的秒数），而不是Unix纪元。服务器将这些转换为人类可读的ISO 8601格式。

x-callback-url方案

Bear支持16个URL方案操作。文档：https://bear.app/faq/x-callback-url-scheme-documentation/

服务器使用以下操作进行写入：

/create --新笔记
/add-text --追加、前置、替换、节目标更新
/add-file --文件附件（base64编码）
/trash, /archive --笔记生命周期
/rename-tag, /delete-tag --标签管理
/grab-url --网页剪辑

所有通话均使用 open -g （macOS背景打开）以避免窃取焦点。

标题与ID解析

当a title 如果为写入操作提供了支持，服务器首先会通过SQLite查找笔记的唯一标识符。这避免了多个注释共享相似标题时的歧义。这 id 参数始终优先，并直接使用。

局限性

仅限macOS --取决于Bear的SQLite路径和macOS open 命令
无写入确认 --x-callback-url不向CLI调用者返回结果（仅通过x-success向其他应用程序返回结果）。写操作是即发即弃。服务器在写入之前验证笔记是否存在，但无法确认写入成功。
文件大小限制 --由于URL方案长度限制，文件附件约为750KB
不支持加密笔记 --加密的笔记无法通过SQLite读取（内容在 ZENCRYPTEDDATA 斑点）
熊一定在跑 --x-callback-url写入需要Bear打开（可以在后台）

示例提示

Search my Bear notes for "project plan"

Read my "Meeting Notes" Bear note

Create a Bear note called "Sprint Retro" with sections for "What went well", "What didn't", and "Action items"

Append "- Completed the deploy" to my "Sprint Retro" note under the "What went well" section

Show me Bear notes with incomplete todos

Save this page to Bear: https://example.com/article

Attach the screenshot at ~/Desktop/screenshot.png to my "Bug Report" Bear note

Archive my "Old Project" Bear note

许可证

麻省理工学院

使用说明

Bear MCP服务器

为什么

建筑

需求

安装

克劳德代码

克劳德桌面版

其他MCP客户端

工具（15）

读取工具（通过SQLite）

bear_search

bear_read_note

bear_list_tags

bear_list_todos

编写工具（通过x-callback-url）

bear_create_note

bear_append_to_note

bear_update_section

bear_add_tags

bear_rename_tag

bear_delete_tag

bear_trash_note

bear_archive_note

bear_grab_url

bear_add_file

bear_create_from_template