English Français العربية

Shiori MCP

السجل الرسمي أخرى

MCP server for Shiori bookmark management and tag workflows.

الشيفرة المصدرية الموقع التوثيق

ماذا يمكنك أن تفعل مع 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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

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 (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>"
            }
        }
    }
}

متغيرات البيئة

  • SHIORI_BASE_URL إلزامي Base URL of the Shiori instance, e.g. https://shiori.example.com
  • SHIORI_SESSION_ID سري Existing Shiori session id; skips login if provided
  • SHIORI_USERNAME Shiori username; required unless SHIORI_SESSION_ID is set
  • SHIORI_PASSWORD سري Shiori password; required unless SHIORI_SESSION_ID is set

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  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.

الأسئلة الشائعة

ما هو Shiori MCP؟

MCP server for Shiori bookmark management and tag workflows.

كيف أثبّت 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 من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Shiori MCP إلى مفتاح API؟

نعم. يتطلب SHIORI_BASE_URL, SHIORI_SESSION_ID, SHIORI_PASSWORD، وتضبطها في إعداداته.

هل Shiori MCP مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون Shiori MCP؟

ينشره rusty4444. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.