Skip to main content
Glama

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.

Related MCP server: Nemo

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.

Available Tools

17 tools
wallabag_add_entryC

Save a URL as a wallabag entry.

Inputs: url (required), tags, title, archive, +1 more. Returns: result

wallabag_add_tags_to_entryC

Add one or more tags to a wallabag entry.

Inputs: tags (required), entry_id (required). Returns: result

wallabag_archive_entryC

Mark a wallabag entry as archived/read.

Inputs: entry_id (required). Returns: result

wallabag_create_annotationC

Create an annotation on a wallabag entry.

Inputs: text (required), quote (required), entry_id (required), ranges_json. Returns: result

wallabag_delete_annotationC

Delete a wallabag annotation.

Inputs: annotation_id (required). Returns: result

wallabag_delete_entryC

Delete a wallabag entry.

Inputs: entry_id (required). Returns: result

wallabag_delete_tagB

Delete a wallabag tag globally.

Inputs: tag_id (required). Returns: result

wallabag_get_entryC

Get a wallabag entry/article by id.

Inputs: entry_id (required), include_content. Returns: result

wallabag_health_checkA

Verify wallabag API connectivity and authentication with a tiny read-only request.

Inputs: no named parameters. Returns: result

wallabag_list_annotationsB

List annotations for a wallabag entry.

Inputs: entry_id (required). Returns: result

wallabag_list_entriesC

List wallabag entries/articles with filters and pagination.

Inputs: page, sort, tags, order, +5 more. Returns: result

wallabag_list_tagsA

List tags known to the wallabag account.

Inputs: no named parameters. Returns: result

wallabag_reload_entryC

Ask wallabag to refetch/reparse the original article URL.

Inputs: entry_id (required). Returns: result

wallabag_star_entryC

Mark a wallabag entry as starred/favourite.

Inputs: entry_id (required). Returns: result

wallabag_unarchive_entryB

Mark a wallabag entry as unarchived/unread.

Inputs: entry_id (required). Returns: result

wallabag_unstar_entryB

Remove starred/favourite state from a wallabag entry.

Inputs: entry_id (required). Returns: result

wallabag_update_entryC

Update metadata/state for a wallabag entry.

Inputs: entry_id (required), url, tags, title, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 17 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action (entries, tags, annotations, health), and the archive/unarchive and star/unstar pairs are clearly differentiated. The only mild overlap is between wallabag_update_entry and the specialized state tools (archive/star/reload), but descriptions help distinguish them.

    Naming Consistency5/5

    Every tool follows a uniform wallabag_ prefix plus a consistent verb_noun pattern (list_entries, get_entry, delete_annotation, unarchive_entry). Even paired opposites (archive/unarchive, star/unstar) are named symmetrically.

    Tool Count4/5

    17 tools is slightly above the ideal 3-15 range, but each tool earns its place across three domains (entries, tags, annotations) plus a health check. No redundant tools bloat the surface.

    Completeness4/5

    Entries have full CRUD plus state and reload operations, and annotations cover list/create/delete. Minor gaps exist: no tool to remove a specific tag from an entry, and no annotation update, but core workflows are covered.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server enabling AI assistants to store, retrieve, and manage contextual information across conversations with features like persistent memory, advanced search, tagging, and privacy controls.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables users to transform AI conversations into a structured, searchable knowledge base by saving ideas, code snippets, bookmarks, and reminders. It supports persistent storage through Supabase or PostgreSQL and includes webhook integrations for automating workflows with external tools.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables AI assistants to manage Context Repo prompts, documents, and collections with semantic search and progressive disclosure navigation.
      14 npm
      1
      MIT