wallabag MCP

wallabag MCP

オープンソースの「あとで読む」サービスである wallabag 用の Model Context Protocol（MCP）サーバーです。

このサーバーは、一般的な wallabag のワークフロー向けに、AI アシスタントが利用できる構造化されたインターフェースを提供します。

• 読み取り専用の簡単なヘルスチェックで、接続と認証を確認します
• 保存した記事を一覧表示、絞り込み、ページ分割して取得します
• エントリーのメタデータまたは抽出済みの全文を取得します
• 新しい URL を保存します
• エントリーをアーカイブ／アーカイブ解除、スターの追加／解除します
• 記事の抽出を再読み込み／再取得します
• エントリーを削除します
• タグを一覧表示、追加します
• アノテーションを一覧表示、作成、削除します

このプロジェクトの目的

wallabag はセルフホスト環境で広く使われていますが、API は OAuth ベースで、汎用 LLM ツールから利用するには扱いにくいものです。この 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 インスタンスの Developer / API clients から 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	エントリーを 1 件取得します。抽出済みの全文を含めることもできます
wallabag_add_entry	URL を wallabag に保存します
wallabag_update_entry	タイトル、URL、アーカイブ／スターの状態、またはタグを更新します
wallabag_archive_entry	エントリーをアーカイブ済み／既読としてマークします
wallabag_unarchive_entry	エントリーをアーカイブ解除済み／未読としてマークします
wallabag_star_entry	エントリーにスターを付けます
wallabag_unstar_entry	スターを解除します
wallabag_reload_entry	元の URL の再取得／再解析を wallabag に依頼します
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 シークレットは環境変数またはシークレットマネージャーで管理し、ソース管理には決して含めないでください。