X Bookmarks MCP

x书签-mcp

完全本地的、隐私优先的MCP服务器，将导出的X/Twitter书签转化为可搜索的、丰富的知识库，供Claude Desktop和Claude Code使用。

该项目探讨了个人知识、本地优先数据和MCP工具如何使AI助手更有用，而无需将私人书签数据发送给第三方服务。

 

我为什么建造这个

我在X上保存了很多有用的帖子、帖子、工具和想法，但书签很快就变成了一个黑洞：很容易保存，很难找到，以后几乎不可能变成有用的东西。

我想要一个本地系统，可以导入我导出的书签，丰富链接的内容，自动标记主题，并通过MCP向Claude公开所有内容，同时保持数据私有并在我的控制之下。

这个项目帮助我练习了MCP服务器设计、本地优先工具、SQLite全文搜索、Docker工作流、异步丰富、私有数据处理和人工智能辅助知识管理。

投资组合亮点

• 本地首个AI工具： 没有X API密钥，没有遥测，没有第三方书签数据库。
• MCP集成： 为Claude Desktop/Claude Code提供了8个工具，用于搜索、浏览、标记和汇总书签。
• 可搜索的知识库： SQLite+FTS5全文搜索书签文本、线程文本、注释、标签和丰富的URL。
• 异步富集： 获取链接页面并提取可读内容，以便更好地进行搜索和摘要。
• Docker支持： 可以在本地运行，也可以通过Docker/Docker Compose运行。
• 质量检查： 测试、覆盖目标、格式化/linting命令和私有数据扫描器。

它的作用

• 100%离线 -没有X API密钥，没有第三方服务，没有遥测
• 全文搜索 跨推文文本、线程、链接页面内容、注释和标签
• 自动富集 --从书签中的URL获取和提取内容
• MCP集成 --Claude可使用8个工具进行搜索、浏览、标记和总结

快速开始

1.导出书签

使用浏览器扩展程序，如 twitter网络导出器 将X书签导出为JSON。

将导出保存到 data/exports/bookmarks.json.

2.安装

git clone https://github.com/p0ki/x-bookmarks-mcp.git
cd x-bookmarks-mcp
pip install -r requirements.txt

3.引进和丰富

python -m src import data/exports/bookmarks.json
python -m src enrich

4.联系克劳德

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "xbookmarks": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/x-bookmarks-mcp"
    }
  }
}

更换 /absolute/path/to/x-bookmarks-mcp 带有克隆的完整路径。

安装

git clone https://github.com/p0ki/x-bookmarks-mcp.git
cd x-bookmarks-mcp
pip install -r requirements.txt

需要Python 3.11或更高版本。所有依赖项都列在 requirements.txt.

用法

CLI命令

# Import bookmarks from JSON export
python -m src import data/exports/bookmarks.json

# Fetch and extract content from URLs in bookmarks
python -m src enrich

# Re-fetch already-enriched bookmarks
python -m src enrich --refresh

# Re-run auto-tagging on all bookmarks
python -m src retag

# Show collection statistics
python -m src stats

# Enable verbose logging
python -m src -v import data/exports/bookmarks.json

MCP服务器

python -m src.server

该服务器在stdio上运行，设计为由Claude Desktop或Claude Code启动。

码头工人

塑造形象

docker build -t xbookmarks-mcp .

通过Docker运行MCP服务器

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "xbookmarks": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/xbookmarks/data:/app/data",
        "-v", "/absolute/path/to/xbookmarks/config.yaml:/app/config.yaml:ro",
        "xbookmarks-mcp"
      ]
    }
  }
}

更换 /absolute/path/to/xbookmarks 带有本地克隆的完整路径。相对路径在这里不起作用，因为Claude Desktop从自己的工作目录启动容器。

通过Docker Compose命令行界面

# Import bookmarks
docker compose run --rm xbookmarks-cli import data/exports/bookmarks.json

# Enrich bookmarks
docker compose run --rm xbookmarks-cli enrich

# Show stats
docker compose run --rm xbookmarks-cli stats

运作原理

bookmarks.json ──▶ ingest ──▶ SQLite DB
                                 │
                            enrich (async)
                            fetch URLs ──▶ extract content
                                 │
                            auto-tag (keyword rules)
                                 │
                         MCP server (stdio)
                                 │
                         Claude Desktop / Claude Code

1. 摄取 --解析JSON导出，使用FTS5全文搜索将书签存储在SQLite中
2. 丰富 --异步从书签中获取URL，使用trafilatura提取可读内容
3. 自动标记 --应用基于关键字的规则 config.yaml 对书签进行分类
4. MCP服务器 --通过stdio公开了8个工具，供Claude搜索、浏览和组织书签

MCP工具

配置

环境变量

标记规则（config.yaml）

tag_rules:
  claude-code:
    - "claude code"
    - "claude-code"
  mcp:
    - "mcp"
    - "model context protocol"

当在推文文本、帖子文本或丰富的页面内容中发现任何关键字时，书签会自动标记。

发展

# Clone
git clone https://github.com/p0ki/x-bookmarks-mcp.git
cd x-bookmarks-mcp

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=src --cov-fail-under=80 -v

# Lint
ruff check src/ tests/
black --check src/ tests/
isort --check-only src/ tests/

# Run private data scanner
python scripts/check_private_data.py

许可证

麻省理工学院