wallabag MCP

wallabag MCP

这是一个面向 wallabag 的模型上下文协议（MCP）服务。wallabag 是一款开源的稍后阅读服务。

此服务为 AI 助手提供了一个结构化接口，用于处理常见的 wallabag 工作流：

• 通过一个轻量的只读健康检查验证连接和身份验证
• 列出、筛选已保存的文章，并分页浏览
• 获取条目元数据或提取后的完整内容
• 保存新的 URL
• 归档/取消归档条目，并为条目加星/取消加星
• 重新加载/重新抓取文章内容
• 删除条目
• 列出并添加标签
• 列出、创建和删除批注

为什么要开发此服务

wallabag 在可自托管环境中广泛使用，但其 API 基于 OAuth，不太适合通用的大模型工具。此 MCP 服务封装了重要的条目、标签和批注操作，并提供了适合 AI 使用的接口和文档化参数。

安装

pipx install git+https://github.com/rusty4444/wallabag-mcp.git

或者从代码检出目录安装：

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 客户端配置

{
  "mcpServers": {
    "wallabag": {
      "command": "wallabag-mcp",
      "env": {
        "WALLABAG_BASE_URL": "https://wallabag.example.com",
        "WALLABAG_CLIENT_ID": "your-client-id",
        "WALLABAG_CLIENT_SECRET": "your-client-secret",
        "WALLABAG_USERNAME": "your-username",
        "WALLABAG_PASSWORD": "your-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	删除批注

开发与验证

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 密钥保存在环境变量或密钥管理器中，切勿提交到源代码管理中。