wallabag
Connects to a self-hosted Wallabag server via its REST API, providing tools to manage saved entries, tags, annotations, search, configuration and server info, with optional user management and guarded write operations.
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 search my wallabag for articles about rust"
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 connector for a Wallabag server. It speaks the REST API over stdio and over stateless Streamable HTTP on 127.0.0.1.
Wallabag is MIT-licensed software. This connector does not copy that PHP. It only calls the HTTP API on the server you configure. It is not affiliated with Wallabag. Create an API client in your Wallabag account under Developer, then use the OAuth2 password grant, or pass a pre-issued access token.
The operations table is generated from vendor/routes.json, a route snapshot derived from wallabag 2.6.15 ApiBundle controllers (MIT). The snapshot has 35 routes. This connector covers 29 of them in 7 tools. It leaves out 6 endpoints that export files or serve the HTML developer portal. scripts/gen-operations.mjs writes src/operations.ts. Do not edit that file by hand.
Self-hosted servers first. There is no default base URL. WALLABAG_BASE_URL is required. A path prefix is allowed, for example https://example.com/wallabag.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.
{
"mcpServers": {
"wallabag": {
"command": "node",
"args": ["/workspace/connectors/wallabag/dist/index.js"],
"env": {
"WALLABAG_BASE_URL": "http://127.0.0.1:80",
"WALLABAG_CLIENT_ID": "...",
"WALLABAG_CLIENT_SECRET": "...",
"WALLABAG_USERNAME": "...",
"WALLABAG_PASSWORD": "...",
"WALLABAG_ALLOW_WRITES": "false",
"WALLABAG_TOOLSETS": "entries,tags,annotations,search,config,info"
}
}
}
}You can set WALLABAG_ACCESS_TOKEN instead of the password-grant variables.
Docker (HTTP, no authentication, keep it on localhost):
docker build -t wallabag .
docker run -p 127.0.0.1:3000:3000 \
-e WALLABAG_BASE_URL=http://127.0.0.1:80 \
-e WALLABAG_ACCESS_TOKEN=... \
wallabagDo not put tokens in the image.
Regenerate the registry after a Wallabag route bump.
npm run gen:operationsscripts/live-check.mjs talks to a real server over stdio. It needs WALLABAG_BASE_URL and either WALLABAG_ACCESS_TOKEN or the password-grant variables. It sets WALLABAG_TOOLSETS=all. Gated writes run only when WALLABAG_ALLOW_WRITES=true. It prints pass or fail lines only. This workspace does not start Wallabag.
Related MCP server: linkwarden-mcp
Config
Variable | Meaning |
| Required. Origin, |
| OAuth2 client id from Developer → create a client. Required with the other password-grant variables when no access token is set. |
| OAuth2 client secret. Redacted in logs, errors, and tool output. |
| Wallabag username or email for the password grant. |
| Wallabag password. Redacted everywhere. |
| Optional pre-issued Bearer token. Used until HTTP 401. If password-grant variables are also set, a 401 tries |
| Must be the literal |
| Comma list of toolsets, or |
| Local request budget. Default 30. Cache hits do not spend it. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain a secret. |
|
|
| HTTP port. Default 3000. Bound to |
Invalid values are reported by field name and issue code. The rejected value is not included. Tokens, passwords, and client secrets are redacted in logs, errors, tool results, thrown messages, and URLs.
Auth is POST /oauth/v2/token with grant_type=password and application/x-www-form-urlencoded, then Authorization: Bearer <access_token>. A stored refresh_token is used after HTTP 401. The connector never puts credentials in the API URL.
Safety
GET is a read. POST, PUT, PATCH, and DELETE are writes.
A write needs confirm: true as a boolean and WALLABAG_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and redacted body, and it sends nothing. Deletes, bulk URL lists, and user registration add a warning line on the tool and on the preview.
PUT /api/user can return a new OAuth client_secret. That value is shown once. Later calls redact it. User email, password, token, refresh_token, and client_secret are redacted. Error text drops stack traces and filesystem paths.
HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400 and 422 are invalid input. HTTP 429 includes Retry-After. Other failures are server, network, or timeout. Response bodies are capped.
Entry export (epub, pdf, and related files) is not exposed. The HTML developer portal is not exposed.
Tools
Default WALLABAG_TOOLSETS publishes 6 tools. WALLABAG_TOOLSETS=all publishes 7 tools (29 operations). Each tool takes action plus optional params, query, body, and confirm.
action help with optional target returns the path, query, and body fields for one action. Descriptions list action names only, so the tool list stays small.
Toolset | Tool | Default |
entries |
| yes |
tags |
| yes |
annotations |
| yes |
search |
| yes |
config |
| yes |
info |
| yes |
user |
| no |
wallabag_config includes GET /api/config and tagging-rule export. wallabag_info includes GET /api/info and GET /api/version.
Available Tools
6 toolswallabag_annotationsADestructive
wallabag_annotations covers the annotations toolset (4 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Writes need confirm set to the boolean true and WALLABAG_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive actions add an extra warning in the preview: deletes, bulk URL lists, and user registration. Actions: delete_by_id, get_by_id, post_by_id, put_by_id.
Inputs: action (required), body, query, params, +2 more.
wallabag_configBRead-only
wallabag_config covers the config toolset (2 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Actions: get, get_taggingrule_export.
Inputs: action (required), body, query, params, +1 more.
wallabag_entriesADestructive
wallabag_entries covers the entries toolset (14 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Writes need confirm set to the boolean true and WALLABAG_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive actions add an extra warning in the preview: deletes, bulk URL lists, and user registration. Actions: delete_by_id, delete_list, delete_tags, delete_tags_list, get, get_by_id, get_exists, get_tags, patch_by_id, patch_reload, post, post_lists, post_tags, post_tags_lists.
Inputs: action (required), body, query, params, +2 more.
wallabag_infoCRead-only
wallabag_info covers the info toolset (2 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Actions: get, get_version.
Inputs: action (required), body, query, params, +1 more.
wallabag_searchCRead-only
wallabag_search covers the search toolset (1 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Actions: get.
Inputs: action (required), body, query, params, +1 more.
wallabag_tagsADestructive
wallabag_tags covers the tags toolset (4 operations). Auth is OAuth2 Bearer from WALLABAG_ACCESS_TOKEN or a password grant. Self-hosted Wallabag first. action help with target returns one action's parameters. Writes need confirm set to the boolean true and WALLABAG_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive actions add an extra warning in the preview: deletes, bulk URL lists, and user registration. Actions: delete_by_id, delete_label, delete_tag_label, get.
Inputs: action (required), body, query, params, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools map to distinct Wallabag resources, but wallabag_entries duplicates tag operations (get_tags, post_tags, delete_tags) that also belong under wallabag_tags. wallabag_search also overlaps with filtered entry listing via wallabag_entries.get, leaving real ambiguity about which tool to choose.
All tool names follow a predictable wallabag_<resource> lowercase snake_case pattern with a uniform prefix. The only minor inconsistency is mixing plural resource nouns (entries, tags, annotations) with singular ones (config, info, search).
Six top-level tools bundle many API operations into coherent resource groups, which is well-scoped for a Wallabag server. This avoids both an overly thin surface and an unwieldy one-tool-per-endpoint explosion.
The core lifecycle is covered: entries CRUD/list/search, annotations CRUD, tags, config, and info. However tag operations are split across entry and tag tools, and account/user or export-style operations are absent or unclear, leaving minor gaps.
Maintenance
Related MCP Connectors
Discover MCP servers and A2A agents; verify, message, post, follow, react, and receive webhooks.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
OAuth-protected, read-only-by-default MCP server for provenance-labeled QuillCaddie project memory.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Related MCP Servers
FlicenseNot gradedqualityFmaintenanceEnables interaction with a read-later and link sharing social feed app, allowing users to manage links, bookmarks, and share through web, API, and MCP.87-- AlicenseNot gradedqualityCmaintenanceMCP server for Linkwarden bookmarks providing read-first search and preserved content access with opt-in write, delete, and collection-delete tools, plus heuristic triage workflows.57 PyPI1MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to search, organize, and read preserved article text from a Linkwarden bookmark manager, supporting both read and write operations with safety confirmations.2880 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading, annotating, and managing a Zotero library from any MCP client.AGPL 3.0