English Français العربية

Shiori MCP

Official registry Other

MCP server for Shiori bookmark management and tag workflows.

Source code Website Documentation

What can you do with Shiori MCP?

  • 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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package shiori-mcp
Claude Code 
claude mcp add shiori-mcp -e 'SHIORI_BASE_URL=<SHIORI_BASE_URL>' -e 'SHIORI_SESSION_ID=<your shiori_session_id>' -e 'SHIORI_USERNAME=<SHIORI_USERNAME>' -e 'SHIORI_PASSWORD=<your shiori_password>' -- uvx shiori-mcp==0.1.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "shiori-mcp": {
            "command": "uvx",
            "args": [
                "shiori-mcp==0.1.0"
            ],
            "env": {
                "SHIORI_BASE_URL": "<SHIORI_BASE_URL>",
                "SHIORI_SESSION_ID": "<your shiori_session_id>",
                "SHIORI_USERNAME": "<SHIORI_USERNAME>",
                "SHIORI_PASSWORD": "<your shiori_password>"
            }
        }
    }
}

Environment variables

  • SHIORI_BASE_URL required Base URL of the Shiori instance, e.g. https://shiori.example.com
  • SHIORI_SESSION_ID secret Existing Shiori session id; skips login if provided
  • SHIORI_USERNAME Shiori username; required unless SHIORI_SESSION_ID is set
  • SHIORI_PASSWORD secret Shiori password; required unless SHIORI_SESSION_ID is set

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Shiori MCP
  2. Capabilities
  3. Installation
  4. Configuration
  5. MCP client config
  6. Tools
  7. Development and validation
  8. API note
  9. Safety

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

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

{
  "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

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.

Frequently asked questions

What is Shiori MCP?

MCP server for Shiori bookmark management and tag workflows.

How do I install Shiori MCP?

It runs on your machine. In Claude Code: claude mcp add shiori-mcp -e 'SHIORI_BASE_URL=<SHIORI_BASE_URL>' -e 'SHIORI_SESSION_ID=<your shiori_session_id>' -e 'SHIORI_USERNAME=<SHIORI_USERNAME>' -e 'SHIORI_PASSWORD=<your shiori_password>' -- uvx shiori-mcp==0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Shiori MCP need an API key?

Yes. It expects SHIORI_BASE_URL, SHIORI_SESSION_ID, SHIORI_PASSWORD, which you set in its configuration.

Is Shiori MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Shiori MCP?

It is published by rusty4444. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.