wallabag-mcp
Allows managing a wallabag read-it-later library, including listing, filtering, adding, archiving, starring, deleting entries, managing tags, and creating/deleting annotations on articles.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wallabag-mcp list my unread articles from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.gitOr 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 |
| Yes | Base URL of your wallabag instance, e.g. |
| Optional | Existing OAuth access token; if set, password grant is skipped |
| Required unless access token is set | OAuth client id from wallabag's developer client page |
| Required unless access token is set | OAuth client secret |
| Required unless access token is set | wallabag username |
| Required unless access token is set | wallabag password |
| No | HTTP timeout in seconds, default |
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 |
| Verify connectivity and authentication with a tiny read-only request |
| List entries with pagination and filters |
| Fetch one entry, optionally including extracted content |
| Save a URL into wallabag |
| Update title, URL, archive/starred state, or tags |
| Mark an entry archived/read |
| Mark an entry unarchived/unread |
| Star/favourite an entry |
| Remove starred/favourite state |
| Ask wallabag to refetch/reparse the original URL |
| Delete an entry |
| List known tags |
| Add comma-separated tags to an entry |
| Delete a tag globally |
| List annotations for an entry |
| Create an annotation on quoted article text |
| 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.pylive_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 toolswallabag_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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceAn 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
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseAqualityAmaintenanceMCP server that turns DOI, URL, or paper titles into structured Markdown full-text with metadata and assets, enabling AI agents to read beyond abstracts.11264MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI assistants to manage Context Repo prompts, documents, and collections with semantic search and progressive disclosure navigation.14 npm1MIT