XBookmark
将X（推特）书签同步到黑曜石保险库的MCP服务器。 多帐户支持、OAuth 2.0 PKCE身份验证和结构化JSON存储。
特性
- 多账户支持 --通过个人资料创建无限X帐户
- 一键OAuth登录 --浏览器打开，回调被捕获，令牌自动保存
- 集中存储 --将所有书签放在一个文件夹中
bookmarks.json（原子写入） - 线程检测 --多推特线程的自动线程获取
- 跨帐户重复数据删除 --来自2个帐户的同一推文书签=1条
- 费率限制处理 --具有自动重试功能的顺序处理
- 两步工作流程 --先同步，后删除（测试安全）
- 人工智能驱动的摘要 —
/xbookmark-digestClaude分析和分类的代码技能
可用工具
| 工具 | 说明 |
|---|---|
| 认证 | |
xbookmark_auth_login(profile) | 一键OAuth——浏览器+回调+令牌交换 |
xbookmark_auth_url(profile) | 获取OAuth授权URL（手动回退） |
xbookmark_auth_callback(code, state) | 完全授权（手动回退） |
xbookmark_auth_status(profile) | 检查身份验证状态（无=所有配置文件） |
xbookmark_auth_logout(profile) | 清除存储的令牌 |
xbookmark_list_profiles() | 列出所有配置文件和身份验证状态 |
| 同步 | |
xbookmark_sync(profile) | 将书签同步到 bookmarks.json |
xbookmark_delete(profile, tweet_ids, limit) | 从X删除已同步的书签（选择性或全部） |
xbookmark_list(profile) | 列出来自X API的书签 |
xbookmark_get_tweet(tweet, profile) | 通过ID或URL（带线程）获取单条推文 |
xbookmark_sync_all() | 通过重复数据删除同步所有配置文件 |
快速安装（Claude代码插件）
将XBookmark与Claude Code结合使用的最简单方法：
- 设置X API凭据 （添加到
~/.bashrc或~/.zshrc):
export X_CLIENT_ID="your_oauth2_client_id"
export X_CLIENT_SECRET="your_client_secret" # optional
export X_REDIRECT_URI="http://localhost:8080/callback" # optional- 安装插件 （克劳德法典）：
/plugin marketplace add isezen/XBookmarks
/plugin install xbookmark@XBookmarks- 重新启动克劳德代码。 MCP服务器在首次启动时自动安装。
- 使用它：
/xbookmark:digest # Analyze all bookmarks
/xbookmark:digest https://x.com/.../12345 # Process single tweet开发人员安装
先决条件
- Python 3.10+
- 紫外线 包管理器（推荐）或pip
- 启用OAuth 2.0的X开发人员帐户
设置
- 克隆并安装
git clone git@github-isezen:isezen/XBookmarks.git
cd XBookmarks
uv sync- 设置环境变量
cp .env.example .env编辑 .env 使用您的X API证书：
X_CLIENT_ID="your_client_id"
X_CLIENT_SECRET="your_client_secret"
X_REDIRECT_URI="http://localhost:8080/callback"- 创建配置 （可选--默认值适用于大多数设置）
mkdir -p ~/.config/XBookmark
cat > ~/.config/XBookmark/config.json **备注**：书签端点需要 **基本层** 访问或按使用次数付费积分。
## 与MCP客户端一起使用
### 克劳德代码/克劳德桌面
添加到MCP设置中：
{ "mcpServers": { "xbookmark": { "command": "/path/to/XBookmarks/.venv/bin/xbookmark-mcp" } } }
### 工作流程
**第一步：身份验证**
"Login to my X account"
代理人打电话来 `xbookmark_auth_login()` --浏览器打开，您授权，令牌保存。
对于多个帐户，请使用配置文件：
"Login to my work X account as 'work'"
**第二步：同步书签**
"Sync my X bookmarks"
代理人打电话来 `xbookmark_sync_all()` 其中：
- 从所有经过身份验证的配置文件下载
- 跨帐户进行重复数据消除
- 保存到 `XBookmarks/bookmarks.json`
- 不从X中删除
**步骤3：处理和分类**
使用 `/xbookmark-digest` 技能（或手动）：
1. 从以下位置读取书签条目 `bookmarks.json`
1. 分析推特内容，获取链接的网址
1. 在黑曜石主题文件夹中创建丰富的笔记
1. 跟踪已处理的推文 `index.json`
**步骤4：从X中删除** （可选）
"Delete processed bookmarks from X"
代理人打电话来 `xbookmark_delete()` （没有profile参数，这会删除
从所有配置文件中）并清理 `bookmarks.json`.
## 数据存储
### 书签.json
所有已同步的书签都存储在 `XBookmarks/bookmarks.json` 作为一个扁平的JSON数组。
每个条目都包含推文文本、作者信息、实体、媒体、帖子回复，
以及源配置文件。写入时使用原子tmp，然后重命名以确保崩溃安全。
### index.json
跟踪哪些推文已被摘要技能处理。
地图 `tweet_id` 到 `{path, date, tags}` 黑曜石交叉引用。
## 发展
### 快速命令
Install with dev dependencies
uv sync --extra dev
Run all tests
.venv/bin/pytest
Run single test
.venv/bin/pytest tests/test_config.py::TestLoadConfig -v
Coverage report
.venv/bin/pytest --cov=src/xbookmark
Lint & format
.venv/bin/ruff check . && .venv/bin/ruff format .
Run MCP server
.venv/bin/xbookmark-mcp
Debug with MCP Inspector
npx @modelcontextprotocol/inspector .venv/bin/xbookmark-mcp
### 项目结构
XBookmarks/ ├── .claude-plugin/ │ └── marketplace.json # Claude Code plugin marketplace ├── plugins/xbookmark/ # Claude Code plugin │ ├── .claude-plugin/plugin.json │ ├── .mcp.json # MCP server config │ ├── commands/ │ │ └── digest.md # AI digest skill (source of truth) │ ├── hooks/hooks.json # SessionStart auto-install hook │ └── scripts/ensure-installed.sh ├── .claude/commands/ │ └── xbookmark-digest.md # Symlink → plugins/xbookmark/commands/digest.md ├── src/xbookmark/ │ ├── config.py # Config loading, lazy singleton │ ├── mcp/ │ │ ├── server.py # FastMCP entry point │ │ ├── tools_auth.py # 6 OAuth 2.0 PKCE auth tools │ │ └── tools_sync.py # 6 sync/delete/list tools │ ├── x_api/ │ │ ├── auth.py # OAuth 2.0 PKCE flow, token storage │ │ ├── callback_server.py # Local HTTP server for one-click login │ │ ├── client.py # Async HTTP client with retry │ │ ├── bookmarks.py # Bookmark CRUD (X API v2) │ │ └── tweets.py # Tweet/thread fetching │ └── obsidian/ │ └── writer.py # Markdown generation, JSON I/O ├── tests/ │ ├── conftest.py # Shared fixtures │ ├── test_config.py │ ├── test_writer.py │ └── test_tools.py ├── docs/ # Architecture & API docs ├── pyproject.toml ├── CLAUDE.md # Claude Code guidance └── README.md
### 测试
- 框架：pytest with `asyncio_mode = "auto"`
- HTTP模拟： `respx` 图书馆
- 固定装置： `tests/conftest.py` （mock_config、mock_auth_manager、mock_tweet等）
- 按模块分类组织的测试
### 代码的风格
- Python 3.10+，规则：E/F/I/N/W/UP
- 现代风格提示： `str | None`, `list[str]`
- 多行结构中的双引号和尾随逗号
## 许可证
麻省理工学院