English Français العربية

wallabag MCP

Official registry Other

MCP server for wallabag read-it-later entries, tags, and annotations.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package wallabag-mcp
Claude Code 
claude mcp add wallabag-mcp -e 'WALLABAG_BASE_URL=<WALLABAG_BASE_URL>' -e 'WALLABAG_ACCESS_TOKEN=<your wallabag_access_token>' -e 'WALLABAG_CLIENT_ID=<WALLABAG_CLIENT_ID>' -e 'WALLABAG_CLIENT_SECRET=<your wallabag_client_secret>' -e 'WALLABAG_USERNAME=<WALLABAG_USERNAME>' -e 'WALLABAG_PASSWORD=<your wallabag_password>' -- uvx wallabag-mcp==0.1.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "wallabag-mcp": {
            "command": "uvx",
            "args": [
                "wallabag-mcp==0.1.0"
            ],
            "env": {
                "WALLABAG_BASE_URL": "<WALLABAG_BASE_URL>",
                "WALLABAG_ACCESS_TOKEN": "<your wallabag_access_token>",
                "WALLABAG_CLIENT_ID": "<WALLABAG_CLIENT_ID>",
                "WALLABAG_CLIENT_SECRET": "<your wallabag_client_secret>",
                "WALLABAG_USERNAME": "<WALLABAG_USERNAME>",
                "WALLABAG_PASSWORD": "<your wallabag_password>"
            }
        }
    }
}

Environment variables

  • WALLABAG_BASE_URL required Base URL of the wallabag instance, e.g. https://wallabag.example.com
  • WALLABAG_ACCESS_TOKEN secret Existing OAuth access token; skips password grant if provided
  • WALLABAG_CLIENT_ID OAuth client id; required unless WALLABAG_ACCESS_TOKEN is set
  • WALLABAG_CLIENT_SECRET secret OAuth client secret; required unless WALLABAG_ACCESS_TOKEN is set
  • WALLABAG_USERNAME wallabag username; required unless WALLABAG_ACCESS_TOKEN is set
  • WALLABAG_PASSWORD secret wallabag password; required unless WALLABAG_ACCESS_TOKEN is set

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. wallabag MCP
  2. Why this exists
  3. Installation
  4. Configuration
  5. MCP client config
  6. Tools
  7. Development and validation
  8. Safety

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:

VariableRequiredDescription
WALLABAG_BASE_URLYesBase URL of your wallabag instance, e.g. https://app.wallabag.it
WALLABAG_ACCESS_TOKENOptionalExisting OAuth access token; if set, password grant is skipped
WALLABAG_CLIENT_IDRequired unless access token is setOAuth client id from wallabag's developer client page
WALLABAG_CLIENT_SECRETRequired unless access token is setOAuth client secret
WALLABAG_USERNAMERequired unless access token is setwallabag username
WALLABAG_PASSWORDRequired unless access token is setwallabag password
WALLABAG_TIMEOUTNoHTTP 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

ToolPurpose
wallabag_health_checkVerify connectivity and authentication with a tiny read-only request
wallabag_list_entriesList entries with pagination and filters
wallabag_get_entryFetch one entry, optionally including extracted content
wallabag_add_entrySave a URL into wallabag
wallabag_update_entryUpdate title, URL, archive/starred state, or tags
wallabag_archive_entryMark an entry archived/read
wallabag_unarchive_entryMark an entry unarchived/unread
wallabag_star_entryStar/favourite an entry
wallabag_unstar_entryRemove starred/favourite state
wallabag_reload_entryAsk wallabag to refetch/reparse the original URL
wallabag_delete_entryDelete an entry
wallabag_list_tagsList known tags
wallabag_add_tags_to_entryAdd comma-separated tags to an entry
wallabag_delete_tagDelete a tag globally
wallabag_list_annotationsList annotations for an entry
wallabag_create_annotationCreate an annotation on quoted article text
wallabag_delete_annotationDelete 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.

Frequently asked questions

What is wallabag MCP?

MCP server for wallabag read-it-later entries, tags, and annotations.

How do I install wallabag MCP?

It runs on your machine. In Claude Code: claude mcp add wallabag-mcp -e 'WALLABAG_BASE_URL=<WALLABAG_BASE_URL>' -e 'WALLABAG_ACCESS_TOKEN=<your wallabag_access_token>' -e 'WALLABAG_CLIENT_ID=<WALLABAG_CLIENT_ID>' -e 'WALLABAG_CLIENT_SECRET=<your wallabag_client_secret>' -e 'WALLABAG_USERNAME=<WALLABAG_USERNAME>' -e 'WALLABAG_PASSWORD=<your wallabag_password>' -- uvx wallabag-mcp==0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does wallabag MCP need an API key?

Yes. It expects WALLABAG_BASE_URL, WALLABAG_ACCESS_TOKEN, WALLABAG_CLIENT_SECRET, WALLABAG_PASSWORD, which you set in its configuration.

Is wallabag MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains wallabag MCP?

It is published by rusty4444. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.