Content
# wallabag MCP
<p align="center">
<a href="https://buymeacoffee.com/rusty4" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
</a>
</p>
<!-- mcp-name: io.github.rusty4444/wallabag-mcp -->
A Model Context Protocol (MCP) server for [wallabag](https://wallabag.org/), 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
```bash
pipx install git+https://github.com/rusty4444/wallabag-mcp.git
```
Or from a checkout:
```bash
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
```json
{
"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
```bash
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.
