内容
# wallabag MCP
<p align="center">
<a href="https://buymeacoffee.com/rusty4" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="给我买杯咖啡" height="50">
</a>
</p>
<!-- mcp-name: io.github.rusty4444/wallabag-mcp -->
一款适用于 [wallabag](https://wallabag.org/)（一款开源的稍后阅读服务）的模型上下文协议（MCP）服务器。
该服务器为 AI 助手提供了一个结构化的接口，用于常见的 wallabag 工作流程：
- 通过一个微小的只读健康检查来验证连接和身份验证
- 列出、筛选和分页浏览已保存的文章
- 获取条目元数据或完整的提取内容
- 保存新的 URL
- 存档/取消存档和标记/取消标记条目
- 重新加载/重新获取文章提取
- 删除条目
- 列出和添加标签
- 列出、创建和删除注释
## 为什么存在
wallabag 在自托管设置中被广泛使用，但其 API 基于 OAuth，对于一般的 LLM 工具来说很麻烦。这个 MCP 服务器封装了重要的条目、标签和注释操作，提供了一个 AI 友好的界面和文档化的参数。
## 安装
```bash
pipx install git+https://github.com/rusty4444/wallabag-mcp.git
```
或从检出:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
## 配置
服务器从环境变量中读取配置：
| 变量 | 必需 | 描述 |
|---|---:|---|
| `WALLABAG_BASE_URL` | 是 | wallabag 实例的基本 URL，例如 `https://app.wallabag.it` |
| `WALLABAG_ACCESS_TOKEN` | 可选 | 现有的 OAuth 访问令牌；如果设置，则跳过密码授权 |
| `WALLABAG_CLIENT_ID` | 如果设置了访问令牌，则不需要 | wallabag 开发者客户端页面的 OAuth 客户端 ID |
| `WALLABAG_CLIENT_SECRET` | 如果设置了访问令牌，则不需要 | OAuth 客户端密钥 |
| `WALLABAG_USERNAME` | 如果设置了访问令牌，则不需要 | wallabag 用户名 |
| `WALLABAG_PASSWORD` | 如果设置了访问令牌，则不需要 | wallabag 密码 |
| `WALLABAG_TIMEOUT` | 否 | 秒为单位的 HTTP 超时，默认为 `20` |
在 wallabag 实例的 **开发者 / API 客户端** 下创建一个 wallabag API 客户端。wallabag 的官方文档展示了针对 `/oauth/v2/token` 的密码授权。
## MCP 客户端配置
```json
{
"mcpServers": {
"wallabag": {
"command": "wallabag-mcp",
"env": {
"WALLABAG_BASE_URL": "https://wallabag.example.com",
"WALLABAG_CLIENT_ID": "您的客户端 ID",
"WALLABAG_CLIENT_SECRET": "您的客户端密钥",
"WALLABAG_USERNAME": "您的用户名",
"WALLABAG_PASSWORD": "您的密码"
}
}
}
}
```
## 工具
| 工具 | 用途 |
|---|---|
| `wallabag_health_check` | 通过一个微小的只读请求验证连接和身份验证 |
| `wallabag_list_entries` | 列出条目，支持分页和筛选 |
| `wallabag_get_entry` | 获取一个条目，可选地包括提取的内容 |
| `wallabag_add_entry` | 将 URL 保存到 wallabag |
| `wallabag_update_entry` | 更新标题、URL、存档/标记状态或标签 |
| `wallabag_archive_entry` | 将条目标记为存档/已读 |
| `wallabag_unarchive_entry` | 将条目标记为取消存档/未读 |
| `wallabag_star_entry` | 标记条目为星标/收藏 |
| `wallabag_unstar_entry` | 取消条目的星标/收藏状态 |
| `wallabag_reload_entry` | 请求 wallabag 重新获取/重新解析原始 URL |
| `wallabag_delete_entry` | 删除条目 |
| `wallabag_list_tags` | 列出已知的标签 |
| `wallabag_add_tags_to_entry` | 向条目添加逗号分隔的标签 |
| `wallabag_delete_tag` | 全局删除标签 |
| `wallabag_list_annotations` | 列出条目的注释 |
| `wallabag_create_annotation` | 在引用的文章文本上创建注释 |
| `wallabag_delete_annotation` | 删除注释 |
## 开发和验证
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_docs_test.py
```
`live_docs_test.py` 验证 wallabag 的公共 API 文档和托管的 API 文档页面，无需账户凭证。变异和身份验证请求行为通过模拟的 HTTP 测试覆盖。
## 安全
具有写权限的工具会修改您的稍后阅读库。请将 OAuth 机密存储在环境变量或机密管理器中，而不是源代码控制中。
