wallabag-mcp 0.1.0

Model Context Protocol server for wallabag read-it-later instances

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:

Variable	Required	Description
WALLABAG_BASE_URL	Yes	Base URL of your wallabag instance, e.g. https://app.wallabag.it
WALLABAG_ACCESS_TOKEN	Optional	Existing OAuth access token; if set, password grant is skipped
WALLABAG_CLIENT_ID	Required unless access token is set	OAuth client id from wallabag's developer client page
WALLABAG_CLIENT_SECRET	Required unless access token is set	OAuth client secret
WALLABAG_USERNAME	Required unless access token is set	wallabag username
WALLABAG_PASSWORD	Required unless access token is set	wallabag password
WALLABAG_TIMEOUT	No	HTTP timeout in seconds, default 20

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

Tool	Purpose
wallabag_health_check	Verify connectivity and authentication with a tiny read-only request
wallabag_list_entries	List entries with pagination and filters
wallabag_get_entry	Fetch one entry, optionally including extracted content
wallabag_add_entry	Save a URL into wallabag
wallabag_update_entry	Update title, URL, archive/starred state, or tags
wallabag_archive_entry	Mark an entry archived/read
wallabag_unarchive_entry	Mark an entry unarchived/unread
wallabag_star_entry	Star/favourite an entry
wallabag_unstar_entry	Remove starred/favourite state
wallabag_reload_entry	Ask wallabag to refetch/reparse the original URL
wallabag_delete_entry	Delete an entry
wallabag_list_tags	List known tags
wallabag_add_tags_to_entry	Add comma-separated tags to an entry
wallabag_delete_tag	Delete a tag globally
wallabag_list_annotations	List annotations for an entry
wallabag_create_annotation	Create an annotation on quoted article text
wallabag_delete_annotation	Delete an annotation

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.