Bookmarks Aware MCP Server

支持书签的MCP服务器

一个模型上下文协议（MCP）服务器，通过自然语言提供对Chrome书签的完全访问——搜索、人工智能丰富和组织。

示例用法

搜索书签

“查找我关于使用SQLite构建持久执行引擎的书签”

代理人打电话来 get_bookmarks 带查询 "durable execution engine SQLite" 并返回：

[
  {
    "url": "https://www.morling.dev/blog/building-durable-execution-engine-with-sqlite/",
    "title": "Building a Durable Execution Engine with SQLite",
    "summary": "A guide to building a durable execution engine using SQLite...",
    "tags": ["sqlite", "distributed-systems", "durable-execution"]
  }
]

用AI元数据丰富书签

“用摘要和标签丰富我的Python教程书签”

代理通过以下方式获取每个页面 fetch_page_content，读取内容，生成摘要和标签，然后通过以下方式存储它们 store_bookmark_metadata。未来的搜索现在包括此元数据。

重新组织书签

“将我的所有机器学习书签移动到bookmark_bar下的新ML文件夹中”

代理人打电话来 create_folder 和 bulk_reorganize 移动书签。更改会立即显示在Chrome中。

特性

• 搜索 --跨URL、标题、摘要和标签的关键字搜索
• 富集 --代理驱动：MCP获取页面，您的代理（Claude、GPT等）生成摘要和标签
• 组织 --移动、重命名、删除和添加书签；直接在Chrome中创建文件夹
• 实时编辑 --可选的Chrome扩展程序桥，可在Chrome运行时进行即时更改
• 撤消/历史记录 --每一个变化都会被跟踪；使用单个工具调用还原任何操作
• 诊断 --内置健康检查可验证设置并识别问题
• 元数据存储 --用于持久摘要和标签的SQLite数据库
• 跨平台 --macOS、Windows、Linux和Chromium支持

安装

1. 确保安装了Python 3.11或更高版本。

1. 创建虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项：

   make setup

MCP客户端配置（光标）

添加到MCP配置文件（通常 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "bookmarks-aware-mcp": {
      "command": "python3",
      "args": ["/absolute/path/to/bookmarks-aware-mcp/src/main.py"]
    }
  }
}

替换 /absolute/path/to/bookmarks-aware-mcp 与这个项目的实际路径。

首次运行

安装和MCP客户端配置后：

1. 问代理人： *“运行书签健康检查”*
2. 代理人打电话来 health_check 并报告是否找到Chrome书签文件、您有多少书签以及任何问题。
3. 如果它找不到你的书签，设置 BOOKMARKS_CHROME_PROFILE 添加到您的Chrome个人资料名称（例如。， "Profile 1").

Chrome扩展程序（推荐）

要在Chrome运行时进行实时书签编辑，请安装配套扩展程序：

1. 打开 chrome://extensions 在Chrome浏览器中
2. 启用 开发者模式 （右上角切换）
3. 点击 加载未打包的 并选择 chrome-extension/ 此项目中的文件夹
4. 出现“书签MCP桥”图标——单击它查看连接状态

当扩展连接时，所有书签写入都通过Chrome的原生API。当它未连接时，服务器会回退到文件编辑（需要先关闭Chrome）。

扩展只需要 bookmarks 权限--无法访问您的浏览历史记录、选项卡或页面内容。通信只能通过WebSocket在本地主机上进行。

可用工具（17）

诊断

搜索

富集

富集流程为 代理驱动：MCP服务器处理获取和存储，而调用代理则进行摘要。不需要LLM设置。

组织

历史记录/撤消

所有写入操作都会创建一个 .bak 在SQLite中备份并记录更改以获得撤消支持。

建筑

src/
├── main.py            # Entry point
├── server.py          # MCP server, 17 tool definitions
├── bookmarks_store.py # Chrome bookmarks read/write/add
├── chrome_bridge.py   # WebSocket bridge to Chrome extension
├── search.py          # Keyword search with metadata support
├── metadata_store.py  # SQLite store (~/.bookmarks-mcp/metadata.db)
├── change_tracker.py  # Change history + undo (bookmark_changes table)
├── enrichment.py      # Page fetching + content extraction
└── config.py          # Configuration via environment variables

chrome-extension/
├── manifest.json      # MV3 extension manifest
├── service-worker.js  # WebSocket client + chrome.bookmarks bridge
├── popup.html/js      # Connection status UI
└── icons/             # Extension icons

浓缩流程

1. Agent calls fetch_page_content(url)
   → MCP fetches page, extracts text via trafilatura, returns content

2. Agent reads content, generates summary + tags using its own model

3. Agent calls store_bookmark_metadata(url, summary, tags)
   → MCP stores metadata in SQLite

4. Future get_bookmarks searches now include the enriched metadata

关键设计决策

• 代理驱动的富集 --服务器中没有LLM。调用代理使用其运行的任何模型进行摘要。零设置，最高质量。
• 本地SQLite元数据 --摘要和标签存储在 ~/.bookmarks-mcp/metadata.db.跟踪跨机器同步作为未来的工作。
• 布里奇首先写道 --当Chrome扩展连接时，写入通过Chrome的本地API进行即时更新。断开连接后回退到文件编辑。
• 使用撤消更改跟踪 --每次写入都记录在SQLite中，并带有before/after状态。任何更改都可以恢复。
• 可扩展搜索 -- SearchEngine 该协议允许稍后在语义搜索中进行交换。

有关权衡和替代方案的完整决策记录，请参阅 决策.md.

配置

服务器从默认位置读取Chrome书签：

• macOS: ~/Library/Application Support/Google/Chrome/Default/Bookmarks
• 视窗: %LOCALAPPDATA%\Google\Chrome\User Data\Default\Bookmarks
• Linux: ~/.config/google-chrome/Default/Bookmarks

环境变量

未来的增强功能

有关计划功能和项目进度，请参阅 项目委员会.

错误处理

• 缺少书签文件：返回带警告的空结果
• JSON格式错误：记录错误，返回空结果
• 页面获取失败：返回错误消息，不会崩溃
• 写入失败：保留备份，报告错误