bookmarks MCP

MCP服务器书签

一种模型上下文协议（MCP）服务器，为AI代理提供对Chrome书签的只读访问，实现书签内容的智能搜索、分析和组织。

特性

• 🔍 搜索书签：按标题、URL或文件夹路径中的关键字查找书签
• 📊 分析收藏：获取书签收藏的统计信息
• 🌐 领域分析：查看您最常为哪些网站添加书签
• 📁 按根筛选：访问书签栏、其他书签或同步书签
• ⚡ 快速性能：基于JSON（无SQLite锁定，Chrome打开时有效！）
• 🔒 只读：使用安全-无需修改书签

用例

• 查找旧书签关于Python测试，我节省了什么
• 发现模式：“我最常参考哪些网站？”
• 整理见解：“这50个开发书签分散在10个文件夹中”
• 重新发现内容：“显示我的所有AI/ML书签”

需求

• Python 3.10或更高版本
• 谷歌Chrome浏览器（带书签）
• MCP兼容的AI代理（例如Goose Desktop）

安装

与Goose桌面配合使用

1. 打开Goose桌面 并前往 设置→ 扩展

1. 点击“添加自定义扩展名”

1. 填写表格：

- 名字: Bookmarks MCP - 命令:

     uvx --with mcp[cli] mcp run [path to mcp code]/server/main.py

替换 [path to mcp code] 使用您的实际路径，例如：

   uvx --with mcp[cli] mcp run [mcp install dir]/bookmarks_mcp/server/main.py

1. 点击“添加” -你准备好了！

与MCP CLI一起使用

# Install dependencies
pip install mcp

# Run the server
python server/main.py

快速开始

步骤1：检查状态

首先，验证您的Chrome书签是否可以访问：

check_bookmarks_file_status()

预期响应：

{
  "status": "ready",
  "bookmarks_path": "/Users/rob/Library/Application Support/Google/Chrome/Default/Bookmarks",
  "file_size": 1234567,
  "total_bookmarks": 1234,
  "total_folders": 56
}

第二步：获取所有书签

检索所有书签：

get_all_bookmarks()

或者只获取特定的根：

get_all_bookmarks(root="bookmark_bar")

步骤3：搜索书签

按关键字查找书签：

search_bookmarks_by_query("github")

在特定字段中搜索：

search_bookmarks_by_query("docs.python.org", search_in=["url"])

步骤4：分析集合

获取概览统计数据：

analyze_bookmarks_overview()

请参阅顶级域名：

analyze_bookmarks_domains(limit=20)

可用工具

1. health_check()

快速测试以验证MCP服务器是否正在运行。

2. check_bookmarks_file_status()

检查Chrome书签文件是否可访问，并获取基本信息。

退货：

• status：“就绪”、“file_not_found”、“拒绝许可”或“错误”
• bookmarks_path：Chrome书签文件的路径
• total_bookmarks：URL书签总数
• total_folders：文件夹总数
• roots：可用根文件夹

3. get_all_bookmarks(root="all", include_folders=True, max_depth=None)

使用过滤选项检索所有Chrome书签。

参数：

• root：“全部”、“书签bar”、“其他”或“已同步”
• include_folders：在结果中包含文件夹条目
• max_depth：要遍历的最大文件夹深度

退货：

• bookmarks：书签条目列表
• summary：检索书签的统计信息

4. search_bookmarks_by_query(query, search_in=None, case_sensitive=False, root="all", max_results=100)

按关键字搜索书签。

参数：

• query：搜索词
• search_in：字段列表-\[“标题”、“url”、“文件夹”\]
• case_sensitive：启用区分大小写的搜索
• root：要搜索哪个根
• max_results：返回的最大结果

退货：

• results：匹配书签
• total_found：结果数量
• search_time_ms：搜索持续时间

5. analyze_bookmarks_overview()

获取有关书签收藏的全面统计数据。

退货：

• total_bookmarks：URL书签总数
• total_folders：文件夹总数
• max_depth：最大文件夹层次结构深度
• date_range：最旧和最新书签日期
• roots_summary：按根分类
• average_bookmarks_per_folder：每个文件夹的平均书签

6. analyze_bookmarks_domains(limit=20)

分析您最常为哪些域名添加书签。

参数：

• limit：要返回的顶级域的最大数量

退货：

• top_domains：包含计数和示例的域统计列表
• unique_domains：唯一域总数
• bookmarked_domains_count：具有多个书签的域

数据结构

每个书签条目包含：

{
    "id": "unique_identifier",
    "name": "Bookmark Title",
    "url": "https://example.com",
    "type": "url",  # or "folder"
    "folder_path": ["Bookmarks Bar", "Dev Resources"],
    "date_added": "2024-01-15T10:30:00",
    "date_added_timestamp": 13278388739951719,
    "indent_level": 1
}

Chrome书签位置

服务器会自动检测Chrome书签文件位置：

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

相对于浏览器历史记录的优势

• ✅ 无文件锁定：Chrome运行时有效
• ✅ JSON格式：简单解析（无SQLite）
• ✅ 树形结构：保留文件夹层次结构
• ✅ 永久的：书签不会像历史记录那样自动删除
• ✅ 精选：只有您有意保存的内容

项目状态

版本：0.1.0（阿尔法）

实现:

• ✅ Chrome书签解析
• ✅ 按标题/URL/文件夹搜索
• ✅ 概述分析
• ✅ 领域分析
• ✅ 跨平台支持（macOS、Windows、Linux）

计划的 （第二阶段）：

• ⏳ 重复检测
• ⏳ 文件夹结构分析
• ⏳ 缓存层（5分钟TTL）
• ⏳ 模糊搜索

未来 （第三阶段）：

• ⏳ 组织建议
• ⏳ Firefox/Safari支持
• ⏳ 与浏览器历史记录集成

发展

项目结构

bookmarks_mcp/
├── server/
│   ├── __init__.py
│   ├── main.py              # MCP server setup
│   ├── bookmarks_parser.py  # JSON parsing and tree traversal
│   └── local_types.py       # Type definitions
├── tests/
│   └── fixtures/
├── README.md
├── TODO.md
├── CHANGELOG.md
└── pyproject.toml

运行测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

故障排除

“file_not_found”错误

原因：未安装Chrome或书签文件不存在。

解决方案:

1. 验证Chrome是否已安装
2. 打开Chrome浏览器并创建至少一个书签
3. 检查错误消息中的路径

“permission_rejected”错误

原因：权限不足，无法读取书签文件。

解决方案:

• macOS/Linux：检查文件权限 ls -l ~/Library/Application Support/Google/Chrome/Default/Bookmarks
• 视窗：以管理员身份运行Goose Desktop

空结果

原因：没有符合您条件的书签，或者书签文件为空。

解决方案:

• 验证您在Chrome中是否有书签
• 尝试 get_all_bookmarks() 无过滤器
• 检查 analyze_bookmarks_overview() 用于统计

更新日志

看 更改日志.md 版本历史。

贡献

这只是用Goose和GMT-4.7完成的一个有趣的副项目

我没有计划支持这一点，但请放心。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 受...启发 浏览器历史记录
• 建于 MCP Python SDK