Shiori MCP

io.github.rusty4444Published by GitHub account rusty4444v0.1.0Updated Oct 24, 2026

MCP server for Shiori bookmark management and tag workflows.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

Lets an assistant manage a self-hosted Shiori bookmark library: list, search, add, update, and delete bookmarks, and manage tags.

What you can do
Connects to a Shiori instance's legacy /api endpoints and exposes tools for bookmark and tag workflows. It can verify connectivity and authentication, list bookmarks, search by title, URL, excerpt, or tag, and fetch a bookmark by id or exact URL. Write tools add bookmarks with tag objects, update them via full payloads or common fields, delete one or many ids, list tags with counts, rename tags, and list accounts visible to the session.
When to use it
Useful when you keep bookmarks in a self-hosted Shiori instance and want an assistant to search, organize, or clean up that library, for example finding bookmarks by tag, adding links with tags, or renaming and pruning tags.
Requirements
Runs locally as a stdio process, installed from PyPI as shiori-mcp and launched with uvx (Python runtime). Requires SHIORI_BASE_URL, plus SHIORI_USERNAME and SHIORI_PASSWORD unless SHIORI_SESSION_ID is supplied. Network access to the Shiori instance is needed; SHIORI_TIMEOUT is optional.
Before you install
The write-capable tools mutate the Shiori bookmark database, including deleting bookmarks by id and renaming tags. Credentials SHIORI_PASSWORD and SHIORI_SESSION_ID are secrets and should be kept in environment variables or a secret manager, never in source control. The server targets Shiori's legacy /api endpoints.

Installation

In SourceWeft

  1. Open Shiori MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Shiori MCP

[Buy Me A Coffee]

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

bash
pipx install git+https://github.com/rusty4444/shiori-mcp.git

Or from a checkout:

bash
python -m venv .venvsource .venv/bin/activatepip install -e .

Configuration

VariableRequiredDescription
SHIORI_BASE_URLYesBase URL of the Shiori instance, e.g. https://shiori.example.com
SHIORI_SESSION_IDOptionalExisting Shiori session id; skips login if provided
SHIORI_USERNAMERequired unless session id is setShiori username
SHIORI_PASSWORDRequired unless session id is setShiori password
SHIORI_TIMEOUTNoHTTP timeout in seconds, default 20

MCP client config

json
{  "mcpServers": {    "shiori": {      "command": "shiori-mcp",      "env": {        "SHIORI_BASE_URL": "https://shiori.example.com",        "SHIORI_USERNAME": "your-username",        "SHIORI_PASSWORD": "your-password"      }    }  }}

Tools

ToolPurpose
shiori_health_checkVerify API connectivity/authentication
shiori_list_bookmarksList bookmarks with client-side limit/offset
shiori_search_bookmarksSearch bookmarks by text and/or tag
shiori_get_bookmarkGet one bookmark by id from the bookmark list
shiori_get_bookmark_by_urlGet one bookmark by exact URL
shiori_add_bookmarkAdd a bookmark with optional tags/archive/public flags
shiori_update_bookmarkUpdate a bookmark using full Shiori bookmark JSON
shiori_update_bookmark_fieldsUpdate common fields without manually constructing full JSON
shiori_delete_bookmarkDelete one bookmark id
shiori_delete_bookmarksDelete bookmark ids from a JSON array
shiori_list_tagsList tags and bookmark counts
shiori_rename_tagRename a tag
shiori_list_accountsList accounts visible to this session

Development and validation

bash
python -m venv .venvsource .venv/bin/activatepython -m pip install --upgrade pippip install -e '.[dev]'ruff check .pytestpython 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.

Source: README.md at commit 005ce95

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts