shiori-mcp
This MCP server provides a full-featured interface to manage a Shiori bookmark manager instance.
Health Check: Verify API connectivity and authentication.
List Bookmarks: Retrieve bookmarks with pagination via limit and offset.
Search Bookmarks: Search by text (matched against title, URL, or excerpt) and/or tag name.
Get Bookmark by ID: Retrieve a single bookmark using its numeric ID.
Get Bookmark by URL: Look up a single bookmark using its exact URL.
Add Bookmark: Save a new bookmark with optional title, excerpt, tags, archive flag, and public/private visibility.
Update Bookmark (Full Payload): Update a bookmark by supplying the full Shiori bookmark JSON object.
Update Bookmark Fields: Patch individual fields (title, excerpt, tags, public flag, archive flag) without constructing the full JSON manually.
Delete Single Bookmark: Remove one bookmark by ID.
Delete Multiple Bookmarks: Remove one or more bookmarks by supplying an array of IDs.
List Tags: Retrieve all tags along with their associated bookmark counts.
Rename Tag: Rename an existing tag by its ID.
List Accounts: View user accounts visible to the authenticated session.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shiori-mcplist my bookmarks tagged 'read-later'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Anybox MCP Server
Installation
pipx install git+https://github.com/rusty4444/shiori-mcp.gitOr from a checkout:
python -m venv .venv
source .venv/bin/activate
pip install -e .Configuration
Variable | Required | Description |
| Yes | Base URL of the Shiori instance, e.g. |
| Optional | Existing Shiori session id; skips login if provided |
| Required unless session id is set | Shiori username |
| Required unless session id is set | Shiori password |
| No | HTTP timeout in seconds, default |
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 |
| Verify API connectivity/authentication |
| List bookmarks with client-side limit/offset |
| Search bookmarks by text and/or tag |
| Get one bookmark by id from the bookmark list |
| Get one bookmark by exact URL |
| Add a bookmark with optional tags/archive/public flags |
| Update a bookmark using full Shiori bookmark JSON |
| Update common fields without manually constructing full JSON |
| Delete one bookmark id |
| Delete bookmark ids from a JSON array |
| List tags and bookmark counts |
| Rename a tag |
| 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.pylive_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.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rusty4444/shiori-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server