About Shiori MCP
Shiori MCP is an MCP server for managing bookmarks in a Shiori instance. It supports bookmark and tag operations, search, and account listing for Shiori users.
Key features
- 01Check Shiori connectivity and authentication
- 02List, search, and retrieve bookmarks
- 03Add, update, and delete bookmarks
- 04List tags and bookmark counts
- 05Rename tags and list visible accounts
Use cases
- 01Find saved links by text or tag
- 02Add or update a bookmark with tags
- 03Review tags and their bookmark counts
MCP support
Exposes Shiori bookmark and tag management tools to MCP clients, including search, account listing, and connectivity checks.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx shiori-mcpSHIORI_BASE_URLBase URL of the Shiori instance, e.g. https://shiori.example.comSHIORI_SESSION_IDSecretExisting Shiori session id; skips login if providedSHIORI_USERNAMEShiori username; required unless SHIORI_SESSION_ID is setSHIORI_PASSWORDSecretShiori password; required unless SHIORI_SESSION_ID is setLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEShiori MCP
A Model Context Protocol (MCP) server for Shiori, the self-hosted bookmark and read-it-later manager.
Capabilities
- Verify Shiori connectivity and authentication
- List bookmarks
- Search bookmarks by title, URL, excerpt, and tag
- Get one bookmark by id or exact URL from the bookmark list
- Add bookmarks with Shiori's required tag-object format
- Update bookmarks via either a full-bookmark payload or common field parameters
- Delete bookmarks by id list
- List tags and bookmark counts
- Rename tags
- List accounts visible to the authenticated session
Installation
pipx install git+https://github.com/rusty4444/shiori-mcp.git
Or from a checkout:
python -m venv .venv
source .venv/bin/activate
pip install -e .
Configuration
| Variable | Required | Description |
|---|---|---|
SHIORI_BASE_URL | Yes | Base URL of the Shiori instance, e.g. https://shiori.example.com |
SHIORI_SESSION_ID | Optional | Existing Shiori session id; skips login if provided |
SHIORI_USERNAME | Required unless session id is set | Shiori username |
SHIORI_PASSWORD | Required unless session id is set | Shiori password |
SHIORI_TIMEOUT | No | HTTP timeout in seconds, default 20 |
MCP client config
{
"mcpServers": {
"shiori": {
"command": "shiori-mcp",
"env": {
"SHIORI_BASE_URL": "https://shiori.example.com",
"SHIORI_USERNAME": "your-username",
"SHIORI_PASSWORD": "your-password"
}
}
}
}
Tools
| Tool | Purpose |
|---|---|
shiori_health_check | Verify API connectivity/authentication |
shiori_list_bookmarks | List bookmarks with client-side limit/offset |
shiori_search_bookmarks | Search bookmarks by text and/or tag |
shiori_get_bookmark | Get one bookmark by id from the bookmark list |
shiori_get_bookmark_by_url | Get one bookmark by exact URL |
shiori_add_bookmark | Add a bookmark with optional tags/archive/public flags |
shiori_update_bookmark | Update a bookmark using full Shiori bookmark JSON |
shiori_update_bookmark_fields | Update common fields without manually constructing full JSON |
shiori_delete_bookmark | Delete one bookmark id |
shiori_delete_bookmarks | Delete bookmark ids from a JSON array |
shiori_list_tags | List tags and bookmark counts |
shiori_rename_tag | Rename a tag |
shiori_list_accounts | List accounts visible to this session |
Development and validation
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_docs_test.py
live_docs_test.py validates Shiori public API documentation and repository pages without credentials. Authenticated read/write API behaviours are covered with mocked HTTP tests.
Optional LLM validation can be run with any configured OpenAI-compatible endpoint. For local Aeon validation, set AEON_BASE_URL and optionally AEON_MODEL / AEON_API_KEY before running python scripts/model_validate.py.
API note
This server targets Shiori's documented legacy API under /api/* because the new API v1 is still documented as in development and self-documented at /swagger/index.html on running instances.
Safety
The write-capable tools mutate a Shiori bookmark database. Keep credentials in environment variables or a secret manager, never in source control.
This project was developed with the assistance of AI tools.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.