# 通过 CLI 连接 AI 与自动化工具

> Mac 版熊掌记的命令行工具，让外部应用、脚本以及 AI 助手能够搜索、读取、创建和编辑笔记。涵盖 Claude 连接器、MCP Server，以及作为底层基础的 bearcli 命令行工具。

Source: https://bear.app/zh/faq/command-line-interface/

Mac 版熊掌记新增了三个工具，让外部应用和脚本可以访问你的笔记：命令行工具（CLI）、Claude 连接器，以及 MCP Server（模型上下文协议服务器）。通过这些工具，你可以在应用之外搜索、读取、创建和编辑笔记，适合用于自动化、脚本处理，或将熊掌记接入 Claude 等 AI 助手。Claude 连接器和 MCP 服务器都基于 bearcli 构建，因此无论你计划使用哪一个，先熟悉 bearcli 都是一个不错的选择。

* **Claude 连接器**：在 Claude 中直接与你的笔记对话，一键完成设置
* **MCP Server**：连接 Claude Code、其他 AI 助手，以及任何支持 MCP 协议的工具
* **bearcli**：另外两个工具所基于的命令行工具

⠀⚠️ 在开始之前，建议先[备份](https://bear.app/zh/faq/backup-restore/)熊掌记

# Claude 连接器
连接器让 Claude 成为你笔记的对话入口。你可以在熊掌记内一键完成设置，无需编辑任何配置文件。

**安装方式：** 在熊掌记中打开 **帮助 → 高级 → 安装 Claude 连接器**，熊掌记会自动完成剩余步骤。

**接下来你可以直接问 Claude：**
* "找出所有超过 30 天未修改、含有未完成待办事项的笔记"
* "总结我写过的所有关于 X 项目的内容"
* "列出我本周创建的笔记，按最后修改时间排序"
* "根据我所有的笔记，你觉得我是一个什么样的人？"

⠀⚠️ Claude 在做出任何更改之前都会请求确认。

# MCP Server
Claude 连接器会自动为 Claude 配置好 MCP Server，本节适用于需要自行连接其他 AI 工具的用户。

[模型上下文协议](https://modelcontextprotocol.io/)（MCP）是一个开放标准，让 AI 助手和其他外部工具能够连接到熊掌记等应用。Claude Code、Cursor 以及越来越多的 AI 助手都支持 MCP。
大多数 MCP 客户端使用相同的 JSON 配置格式：
```
{
  "mcpServers": {
    "bear": {
      "command": "/Applications/Bear.app/Contents/MacOS/bearcli",
      "args": ["mcp-server"]
    }
  }
}
```

配置文件的位置，以及是直接编辑文件还是运行设置命令，因客户端而异。具体操作请参考你所使用工具的 MCP 文档。上方的 `command/args` 格式是通用写法，适用于绝大多数客户端。

连接成功后，客户端会自动识别熊掌记提供的所有操作：搜索、读取、创建、标签管理等。大多数 MCP 客户端在做出更改前会请求确认，请查阅你所用工具的默认设置。

从 Bear 2.9 开始，MCP Server 添加了通过标签来设定笔记访问范围。以 Claude 为例，在 Settings → Extensions 中，你可以配置 `Only Tags` 和 `Exclude Tags`：`Only Tags` 将访问范围限制在指定标签的笔记内，`Exclude Tags` 则隐藏你不希望被访问的笔记。例如，将 `私密` 添加到 `Exclude Tags` 后，Claude 将无法看到任何带有 #私密 标签的笔记。

**工具不支持本地 MCP？** 部分 AI 工具（如基于浏览器的助手或终端 Agent）无法运行本地 MCP Server，但可以执行 shell 命令。在这种情况下，你仍然可以通过 `bearcli` 让 AI 访问你的笔记。让它从 `bearcli help all` 开始，这条命令会一次性输出完整的命令参考，AI 可以从中了解所有可用操作。

# bearcli
`bearcli` 是 Claude 连接器和 MCP Server 的底层命令行工具，直接提供所有笔记操作，包括搜索、读取、创建、追加、标签、固定、附件、归档、移至废纸篓等。它适合以下场景：
* 在 shell 或 cron 中编写笔记操作脚本
* 将笔记内容通过管道传入其他 Unix 工具
* 不借助 AI 直接执行批量编辑

**位置：**
`/Applications/Bear.app/Contents/MacOS/bearcli`

**查看完整帮助：**
`/Applications/Bear.app/Contents/MacOS/bearcli -h`
`/Applications/Bear.app/Contents/MacOS/bearcli search -h`

`-h` 输出的内容是每条命令的完整参考文档。

### 简化命令输入
为了避免每次都输入完整路径，可以在 `~/.zshrc`（或你所用 shell 的对应配置文件）中添加以下别名：
```
alias bearcli='/Applications/Bear.app/Contents/MacOS/bearcli'
```

重新加载 shell（或打开新的终端窗口），之后在任何地方输入 bearcli 即可。
需要注意的是，别名在 shell 脚本或 cron 任务中不会生效。如果你需要在这些场景中调用 `bearcli`，建议改用符号链接，将其添加到 PATH 中：
```
sudo mkdir -p /usr/local/bin
sudo ln -s /Applications/Bear.app/Contents/MacOS/bearcli /usr/local/bin/bearcli
```

# 数据与隐私
* **本地运行**：`bearcli` 读写的是你 Mac 上的本地熊掌记数据库，不经过任何外部服务器
* **需要主动开启**：Claude 连接器和 MCP 服务器只有在你安装并启用后才会运行
* **不会批量上传数据**：连接工具本身不会共享任何内容，AI 助手只能看到特定查询所返回的笔记
* **加密笔记受到保护**：加密笔记可以被列出，但这些工具无法读取或修改其内容

⠀
# 要求与限制
* 需要熊掌记 2.8 或更高版本
* 以上三个工具目前仅支持 macOS
* Claude 连接器需要安装 Claude 桌面应用
* 本文档中的路径均以 `/Applications/Bear.app` 为准，如果你将熊掌记安装在其他位置，请相应调整。