内容
# bear-mcp
一款适用于 [Bear](https://bear.app) 笔记的只读模型上下文协议（MCP）服务器，基于 [bear-query](https://crates.io/crates/bear-query) 构建。该服务器允许像 Claude 这样的 AI 助手搜索、检索和浏览您的 Bear 笔记库。
## 功能
- **搜索笔记** - 使用 Bear 数据库索引的高效全文搜索
- **获取笔记详情** - 直接通过 ID 查找笔记，无需获取所有笔记
- **列出标签** - 浏览 Bear 数据库中的所有标签
- **只读访问** - 安全、非破坏性的查询操作
- **快速 SQLite 访问** - 优化查询，尽量减少开销
- **空安全** - 正确处理缺少内容或元数据的笔记
## 可用工具
### `search_notes`
通过标题或内容搜索 Bear 笔记，可选过滤器。使用 Bear 数据库搜索功能进行高效查询。
**参数：**
- `query`（可选）：搜索文本，用于匹配笔记标题和内容。提供时，进行高效数据库搜索。省略时，返回最近的笔记。
- `pinned_only`（可选）：仅返回固定笔记
- `include_trashed`（可选）：在结果中包含已删除笔记（默认：false）
- `include_archived`（可选）：在结果中包含已归档笔记（默认：false）
- `limit`（可选）：返回结果的最大数量（默认：搜索 50，列表 10）
**示例：**
```json
// 搜索包含“rust programming”的笔记
{
"query": "rust programming",
"limit": 10
}
// 仅列出固定笔记
{
"pinned_only": true
}
// 获取所有笔记，包括已归档的笔记
{
"include_archived": true,
"limit": 100
}
```
### `get_note`
通过唯一 ID 获取特定笔记的完整内容。使用直接数据库查找进行快速检索。
**参数：**
- `note_id`（必填）：要检索的笔记的唯一标识符（UUID）
**示例：**
```json
{
"note_id": "ABC123-DEF456-GHI789"
}
```
**注意：** 此方法通过 ID 直接查找，不会获取所有笔记，因此非常高效。
### `list_tags`
列出 Bear 数据库中的所有标签及其修改日期。
**参数：** 无
## 安装
### 先决条件
- Bear 笔记应用已安装在 macOS 上
- Claude Desktop 或另一个 MCP 兼容的客户端
### 选项 1：从 crates.io 安装（推荐）
```bash
cargo install bear-mcp
```
二进制文件将安装到 `~/.cargo/bin/bear-mcp`（如果您已安装 Rust，该目录应该已经在您的 PATH 中）。
### 选项 2：从源代码构建
```bash
# 克隆仓库
git clone https://github.com/jakeswenson/bear-mcp
cd bear-mcp
# 构建项目
cargo build --release
# 二进制文件位于 target/release/bear-mcp
```
## 配置
### Claude Desktop
将服务器添加到您的 Claude Desktop 配置文件中：
**位置：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**如果通过 cargo install 安装：**
```json
{
"mcpServers": {
"bear": {
"command": "/Users/YOUR_USERNAME/.cargo/bin/bear-mcp"
}
}
}
```
将 `YOUR_USERNAME` 替换为您的实际用户名。您可以通过在终端中运行 `which bear-mcp` 找到确切的路径。
**如果从源代码构建：**
```json
{
"mcpServers": {
"bear": {
"command": "/Users/YOUR_USERNAME/path/to/bear-mcp/target/release/bear-mcp"
}
}
}
```
将 `/Users/YOUR_USERNAME/path/to/bear-mcp` 替换为您的克隆仓库的实际路径。
### 环境变量
服务器使用 `RUST_LOG` 环境变量进行日志记录配置：
```json
{
"mcpServers": {
"bear": {
"command": "/Users/YOUR_USERNAME/.cargo/bin/bear-mcp",
"env": {
"RUST_LOG": "info"
}
}
}
}
```
**日志级别：**
- `error` - 仅错误
- `warn` - 警告和错误
- `info` - 信息消息（默认）
- `debug` - 详细调试
- `trace` - 非常详细的输出
日志写入 stderr 并将出现在 Claude Desktop 的日志中。
## 使用示例
配置完成后，您可以要求 Claude 与您的 Bear 笔记交互：
- “搜索我的 Bear 笔记中关于 Rust 的内容”
- “显示我的固定笔记”
- “列出我的所有 Bear 标签”
- “获取笔记 ABC123-DEF456-GHI789 的完整内容”
- “查找关于机器学习且未归档的笔记”
## 工作原理
服务器直接以只读模式连接到 Bear 的 SQLite 数据库：
- **数据库位置：** `~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite`
- **访问模式：** `SQLITE_OPEN_READ_ONLY`，启用 `PRAGMA query_only = ON`
- **连接策略：** 为避免锁定问题，每个查询创建短连接
服务器使用 [bear-query](https://crates.io/crates/bear-query) 库，该库提供：
- Bear Core Data 结构的规范化视图
- 使用数据库索引的高效搜索 API
- 缺失或不完整数据的空安全处理
- 直接通过 ID 查找笔记，无需获取所有笔记
## 开发
### 在开发环境中运行
```bash
# 以调试日志运行
RUST_LOG=debug cargo run
```
### 测试
您可以使用 MCP Inspector 或通过管道传输 JSON-RPC 消息来测试服务器：
```bash
# 示例：调用 list_tags 工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tags"}}' | cargo run
```
## 架构
- **src/main.rs** - 入口点，设置日志记录和 stdio 传输
- **src/bear_service.rs** - MCP 服务器实现，包含工具定义
- **Cargo.toml** - 依赖项和构建配置
### 关键依赖项
- [`rmcp`](https://crates.io/crates/rmcp) - Rust MCP SDK
- [`bear-query`](https://crates.io/crates/bear-query) - Bear 数据库查询库
- [`tokio`](https://tokio.rs) - 异步运行时
- [`tracing`](https://tracing.rs) - 日志记录和诊断
- [`serde`](https://serde.rs) - 序列化框架
## 限制
- **只读：** 无法创建、修改或删除笔记
- **仅限 macOS：** Bear 是 macOS/iOS 应用；此服务器需要 macOS
- **无实时更新：** 服务器按需查询数据库，而不监视更改
- **必须安装 Bear：** 需要 Bear 的 SQLite 数据库存在
## 故障排除
### “Bear 数据库初始化失败”
- 确保 Bear 已安装并且您至少打开过一次
- 检查数据库文件是否存在：`~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite`
- 验证您对数据库文件具有读取权限
### 服务器未出现在 Claude 中
- 检查 `claude_desktop_config.json` 中的路径是否正确且绝对
- 确保二进制文件可执行：`chmod +x target/release/bear-mcp`
- 在修改配置后重启 Claude Desktop
- 检查 Claude 日志：`~/Library/Logs/Claude/`
### 空结果
- 验证您有 Bear 笔记
- 检查笔记是否已删除/归档，并相应地调整搜索参数
- 尝试 `list_tags` 以确认数据库连接性
## 许可证
[在此添加您的许可证]
## 贡献
[在此添加贡献指南]
## 致谢
- 使用 [rmcp](https://github.com/modelcontextprotocol/rust-sdk) - Rust MCP SDK 构建
- 使用 [bear-query](https://crates.io/crates/bear-query) 进行数据库访问
- 灵感来自模型上下文协议规范
