笔记管理服务器

Bear应用程序MCP服务器

一种模型上下文协议（MCP）服务器，使用其X-callback-URL方案提供与Bear App的集成。该服务器使AI助手能够与Bear笔记进行交互，创建新内容，搜索和管理标签。

特性

• 笔记管理：使用完整的元数据检索创建、打开和修改笔记
• 文本操作：添加、追加、预置或替换现有注释中的文本
• 搜索：搜索带有完整结果数据的注释和标签
• 标签管理：获取、打开、重命名和删除具有实时数据的标签
• 组织：存档、回收和整理笔记
• Web内容：从URL中抓取内容，使用返回的元数据创建笔记
• 特别观点：使用完整笔记列表访问Today、Todo和Untaged笔记集
• 回拨集成：高级x-success回调支持，可实现全面的数据检索
• 无声操作：自定义URL方案可防止回调期间出现不需要的浏览器窗口

需求

• macOS（Bear应用程序仅适用于macOS）
• Bear应用程序已安装并正在运行
• Node.js 18+
• Bear API代币（用于某些操作）

快速安装

chmod +x ./setup.sh && ./setup.sh

手动安装

1. 克隆并转到项目：

git clone https://github.com/bigjeager/bear-mcp-server.git
cd bear-mcp-server/

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 生成二进制文件：

/path/to/bear-mcp-server/dist/index.js

获取Bear API代币

某些操作需要Bear API令牌：

在 macOS 上：

1. 打开Bear应用程序
2. 首选 Help → Advanced → API Token → Copy Token
3. 令牌将被复制到剪贴板

配置

将服务器添加到MCP客户端配置中。对于Claude Desktop，添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "bear": {
      "command": "node",
      "args": ["/path/to/bear-mcp-server/dist/index.js"],
      "env": {
        "BEAR_TOKEN": "your-bear-api-token-here"
      }
    }
  }
}

可用工具

核心笔记操作

• bear_open_note：按ID或标题打开笔记（返回完整的笔记数据和元数据）
• bear_create_note：创建一个包含标题、内容和标签的新笔记（返回笔记ID和标题）
• bear_add_text：在现有注释中添加文本（追加、前置、替换）

搜索与发现

• 熊搜索：按术语和/或标签搜索笔记（返回包含元数据的完整搜索结果）
• bear_get-tags：检索所有可用标签（返回完整标签数组）
• bear_open_tag：打开带有特定标签的笔记（返回带有详细信息的笔记列表）

组织

• bear_trash_note：将笔记移到垃圾箱
• bear_archive_note：存档笔记
• bear_get未标记：获取没有标签的笔记（返回完整的未标记笔记列表）
• bear_getodo：获取标记为todos的笔记（返回带有元数据的todo笔记）
• bear_gettoday：获取今天的笔记（返回包含详细信息的今天的笔记）

标签管理

• bear_name_tag：重命名现有标记
• bear_delete_tag：删除标签

web集成

• bear_grab_url：从网页内容创建笔记（返回创建的笔记ID和标题）

安全说明

• 服务器使用macOS open 执行Bear URL的命令
• API令牌应保持安全，不得共享
• 某些操作要求Bear解锁（不处于锁定状态）
• 无法通过API访问加密的笔记

发展

在开发模式下运行：

npm run dev

生产建设：

npm run build

增强的回拨集成

该服务器利用Bear的x-success回调机制提供全面的数据检索：

• 实时数据：大多数操作返回实际的Bear数据，而不是通用的成功消息
• 完整结果：搜索操作返回包含元数据的完整注释数组
• 立即访问：创建的笔记会返回其ID以进行后续操作
• 元数据：注释包括标题、标识符、标签、日期和内容
• 无声操作：自动关闭HTML响应可最大限度地减少浏览器窗口干扰
• 即时关闭：多种JavaScript方法确保浏览器窗口立即关闭

回调增强工具

以下工具使用高级回调集成来增强数据检索：

• bear_open_note, bear_create_note, bear_search, bear_get_tags
• bear_open_tag, bear_get_untagged, bear_get_todo, bear_get_today, bear_grab_url

技术实现

自动关闭HTTP响应：使用标准 http://localhost:port/callback URL，但返回具有多种浏览器关闭机制的HTML：

• 立即 window.close() JavaScript执行
• 元刷新重定向到 about:blank
• 隐藏式机身造型，防止内容闪烁
• 缓存控制标头以防止浏览器缓存

浏览器窗口最小化：虽然浏览器窗口可能会短暂出现，但它会在几毫秒内自动关闭，提供近乎无声的操作。

局限性

• 仅限macOS（Bear应用程序限制）
• 某些操作需要用户与Bear进行交互
• 回调操作有10秒的超时限制（自动回退）
• 文件附件需要base64编码
• 熊必须解锁才能访问加密纸币
• 浏览器窗口可能会短暂闪烁（毫秒内自动关闭）

许可证

MIT许可证-随意修改和分发

贡献

欢迎投稿！请确保：

• TypeScript编译通过(npm run build)
• Bear URL方案已正确实施
• 回调集成工作正常
• 错误处理全面
• 文档已更新
• 测试用 npm run test （需要Bear App才能实现完整功能）

链接

• 熊应用程序
• Bear X-callback-URL文档
• 模型上下文协议