Wallabag MCP Server

wallabag MCP

A Model Context Protocol (MCP) server for wallabag, the open-source read-it-later service.

This server gives AI assistants a structured interface for common wallabag workflows:

• Verify connectivity and authentication with a tiny read-only health check
• List, filter, and page through saved articles
• Fetch entry metadata or full extracted content
• Save new URLs
• Archive/unarchive and star/unstar entries
• Reload/refetch article extraction
• Delete entries
• List and add tags
• List, create, and delete annotations

Why this exists

wallabag is widely used in self-hosted setups, but its API is OAuth-based and awkward for general LLM tools. This MCP server wraps the important entry, tag, and annotation operations with an AI-friendly surface and documented parameters.

Installation

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

Or from a checkout:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

The server reads configuration from environment variables:

Create a wallabag API client from your wallabag instance under Developer / API clients. wallabag's official docs show the password grant against /oauth/v2/token.

MCP client config

{
  "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"
      }
    }
  }
}

Tools

Development and validation

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 validates wallabag's public API documentation and the hosted API docs page without needing account credentials. Mutation and authenticated request behaviours are covered with mocked HTTP tests.

Safety

Write-capable tools mutate your read-it-later library. Keep OAuth secrets in environment variables or a secret manager, never in source control.