Shiori MCP

Shiori MCP

一个用于 Shiori 的模型上下文协议（MCP）服务。Shiori 是一款可自托管的书签和稍后阅读管理工具。

功能

• 验证 Shiori 的连接和身份验证
• 列出书签
• 按标题、URL、摘要和标签搜索书签
• 从书签列表中按 ID 或精确 URL 获取单个书签
• 使用 Shiori 要求的标签对象格式添加书签
• 通过完整书签负载或常用字段参数更新书签
• 按 ID 列表删除书签
• 列出标签和书签数量
• 重命名标签
• 列出经过身份验证的会话可见的账户

安装

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

或者从检出目录安装：

python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

变量	必需	描述
SHIORI_BASE_URL	是	Shiori 实例的基本 URL，例如 https://shiori.example.com
SHIORI_SESSION_ID	否	已有的 Shiori 会话 ID；如果提供，则跳过登录
SHIORI_USERNAME	除非已设置会话 ID，否则必需	Shiori 用户名
SHIORI_PASSWORD	除非已设置会话 ID，否则必需	Shiori 密码
SHIORI_TIMEOUT	否	HTTP 超时时间（秒），默认为 20

MCP 客户端配置

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

工具

工具	用途
shiori_health_check	验证 API 连接和身份验证
shiori_list_bookmarks	列出书签，并在客户端应用 limit/offset
shiori_search_bookmarks	按文本和/或标签搜索书签
shiori_get_bookmark	从书签列表中按 ID 获取单个书签
shiori_get_bookmark_by_url	按精确 URL 获取单个书签
shiori_add_bookmark	添加书签，并可选设置标签、归档和公开标记
shiori_update_bookmark	使用完整的 Shiori 书签 JSON 更新书签
shiori_update_bookmark_fields	更新常用字段，无需手动构造完整 JSON
shiori_delete_bookmark	删除一个书签 ID
shiori_delete_bookmarks	从 JSON 数组中删除书签 ID
shiori_list_tags	列出标签和书签数量
shiori_rename_tag	重命名标签
shiori_list_accounts	列出此会话可见的账户

开发与验证

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 无需凭据即可验证 Shiori 公共 API 文档和仓库页面。经过身份验证的读写 API 行为通过模拟 HTTP 测试覆盖。

可选的 LLM 验证可使用任何已配置的 OpenAI 兼容端点运行。若要在本地进行 Aeon 验证，请在运行 python scripts/model_validate.py 前设置 AEON_BASE_URL，并可选设置 AEON_MODEL / AEON_API_KEY。

API 说明

本服务使用 Shiori 文档所述的旧版 /api/* API，因为新版 API v1 仍被标记为开发中，并且在运行中的实例上通过 /swagger/index.html 提供自文档。

安全

具备写入能力的工具会修改 Shiori 书签数据库。请将凭据保存在环境变量或机密管理器中，切勿将其提交到源代码管理系统。

本项目在 AI 工具的协助下开发。