Shiori 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.