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
| Variable | Required | Description |
|---|---|---|
SHIORI_BASE_URL |
Yes | Base URL of the Shiori instance, e.g. https://shiori.example.com |
SHIORI_SESSION_ID |
Optional | Existing Shiori session id; skips login if provided |
SHIORI_USERNAME |
Required unless session id is set | Shiori username |
SHIORI_PASSWORD |
Required unless session id is set | Shiori password |
SHIORI_TIMEOUT |
No | HTTP 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
| Tool | Purpose |
|---|---|
shiori_health_check |
Verify API connectivity/authentication |
shiori_list_bookmarks |
List bookmarks with client-side limit/offset |
shiori_search_bookmarks |
Search bookmarks by text and/or tag |
shiori_get_bookmark |
Get one bookmark by id from the bookmark list |
shiori_get_bookmark_by_url |
Get one bookmark by exact URL |
shiori_add_bookmark |
Add a bookmark with optional tags/archive/public flags |
shiori_update_bookmark |
Update a bookmark using full Shiori bookmark JSON |
shiori_update_bookmark_fields |
Update common fields without manually constructing full JSON |
shiori_delete_bookmark |
Delete one bookmark id |
shiori_delete_bookmarks |
Delete bookmark ids from a JSON array |
shiori_list_tags |
List tags and bookmark counts |
shiori_rename_tag |
Rename a tag |
shiori_list_accounts |
List accounts visible to this session |
Development and validation
python -m venv .venv
source .venv/bin/activate
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.
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.
Metadata
Release files for shiori-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shiori_mcp-0.1.0.tar.gz | 12.5 kB | Without provenance | Details for shiori_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shiori_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for shiori_mcp-0.1.0-py3-none-any.whl |
Total release size: 21.5 kB
Release files / shiori_mcp-0.1.0.tar.gz
| Download URL | shiori_mcp-0.1.0.tar.gz |
|---|---|
| Size | 12.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec3d821e3e65f72a2182536da28fcc0f0d9579ae4683437df8323bf0dac2a877
|
|
BLAKE2b-256 checksum How to use checksums |
e090dec67a515e95989a22c4e4169a431b42258611d208b3d1fa4f89a9cef3a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / shiori_mcp-0.1.0-py3-none-any.whl
| Download URL | shiori_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bae0cb2d6bd216122be0749658f5a8dbf30f67f8c0851cc282bd88ca7d8116c5
|
|
BLAKE2b-256 checksum How to use checksums |
71655527f268ea0f779776fb6fef1f43491b5177cdd0c57528ad15bebbf77251
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for shiori-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.