# Bookmarks MCP

一个基于 FastMCP 的浏览器书签管理服务器，支持 Chrome 和 Edge 浏览器。通过 MCP 协议，让 AI 助手（如 Claude）可以搜索、浏览、添加和删除书签。

> ⚠️ **隐私安全警告**：本项目会直接读取和修改你本地的浏览器书签文件。使用前请务必阅读下方的[隐私与安全](#-隐私与安全)章节。

## 功能

| 工具 | 功能 |
|------|------|
| `search_bookmarks` | 按关键词搜索书签（匹配标题和 URL，不区分大小写） |
| `list_folders` | 列出所有书签文件夹及包含的书签数量 |
| `list_bookmarks` | 列出指定文件夹下的书签 |
| `recent_bookmarks` | 获取最近添加的书签 |
| `add_bookmark` | 添加一条新书签 |
| `remove_bookmark` | 删除一条书签 |

## 快速开始

### 安装

```bash
cd chrome-bookmanager
pip install -e .
```

### 运行

```bash
# stdio 模式（Claude Desktop 默认使用此模式）
bookmarks-mcp

# 开发调试
python -m bookmarks_mcp.server
```

### Claude Desktop 配置

编辑 `claude_desktop_config.json`，添加以下配置：

```json
{
  "mcpServers": {
    "bookmarks-mcp": {
      "command": "python",
      "args": ["-m", "bookmarks_mcp.server"]
    }
  }
}
```

## 项目结构

```
bookmarks-mcp/
├── pyproject.toml
├── README.md
├── src/
│   └── bookmarks_mcp/
│       ├── __init__.py
│       ├── server.py          # FastMCP 入口 + 工具注册
│       ├── bookmarks/
│       │   ├── __init__.py
│       │   ├── manager.py     # 通用 CRUD 操作（外观模式）
│       │   └── models.py      # Pydantic 数据模型
│       ├── browsers/
│       │   ├── __init__.py
│       │   ├── base.py        # 浏览器适配器基类（抽象接口）
│       │   ├── chrome.py      # Chrome 适配器
│       │   └── edge.py        # Edge 适配器（继承 Chrome）
│       └── utils/
│           ├── __init__.py
│           └── paths.py       # 跨平台路径工具
└── tests/
    ├── __init__.py
    └── test_chrome.py
```

## 设计思路

- **适配器模式**：`base.py` 定义抽象接口，`chrome.py` 和 `edge.py` 分别实现。Edge 继承 Chrome（同为 Chromium 内核，书签格式一致），只覆盖路径和类型。
- **外观模式**：`BookmarkManager` 对外暴露简洁的 CRUD 接口，内部委托给具体浏览器适配器。
- **数据模型分离**：所有数据结构用 Pydantic 定义，保证类型安全。
- **只读优先**：先从只读工具（搜索、列出）开始，稳定后再加写入功能。

## 支持的浏览器

| 浏览器 | 支持平台 | 书签文件路径 |
|--------|----------|-------------|
| Google Chrome | Windows / macOS / Linux | `%LOCALAPPDATA%/Google/Chrome/User Data/Default/Bookmarks` |
| Microsoft Edge | Windows / macOS / Linux | `%LOCALAPPDATA%/Microsoft/Edge/User Data/Default/Bookmarks` |

## ⚠️ 隐私与安全

### 已知隐私风险

该工具在提供便利的同时，也引入了以下隐私风险，请在使用前充分了解：

1. **读取本地书签数据**：工具会直接读取 Chrome/Edge 的书签文件（`Bookmarks`），其中包含你所有保存的 URL、标题、文件夹结构和添加时间。这些数据可能包含敏感信息（如内部系统地址、个人账户页面、私密网站等）。

2. **修改书签文件**：`add_bookmark` 和 `remove_bookmark` 工具会直接写入你的书签文件，可能导致书签数据被意外修改或删除。

3. **数据可能被发送至第三方**：作为 MCP 服务器，书签数据通过 AI 客户端（如 Claude Desktop）处理后，可能会被发送到第三方 AI 服务商的服务器。你的书签 URL 和标题可能被用于模型训练或分析。

4. **无用户确认机制**：当前版本在操作书签前不会弹出确认提示，所有操作在 AI 调用时立即执行。

5. **无访问控制**：所有工具方法均可被任意调用，没有权限分级或限制机制。

### 安全建议

- **仅用于个人学习环境**：建议只在本地开发和学习场景下使用，不要在生产环境或共享机器上运行。
- **避免在 AI 会话中搜索敏感书签**：不要通过此工具搜索或浏览包含敏感信息的书签。
- **定期检查变更**：如果启用了写入功能，建议定期检查书签文件是否被意外修改。
- **使用专用浏览器配置文件**：考虑为 AI 工具使用单独的浏览器配置文件，与日常工作环境隔离。
- **阅读 AI 客户端的隐私政策**：了解与你使用的 AI 客户端（如 Claude）相关的数据处理政策。

### 数据流说明

```
本地浏览器书签文件 (Bookmarks JSON)
    ↓ 读取
Bookmarks MCP Server (本地进程)
    ↓ 通过 MCP 协议 (stdio)
AI 客户端 (如 Claude Desktop)
    ↓ 可能发送至云端
AI 服务提供商服务器
```

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 代码检查
ruff check src/
```

## 许可

MIT