MCP Server · Shiori

Overview

Shiori's MCP server lets AI coding assistants and other tools access your saved links. It supports the standard Model Context Protocol with OAuth authentication — add the server URL, approve access in the browser, then verify with whoami.

The fastest way to connect: copy the setup prompt above and paste it into your AI client. Or follow the client steps below, then Verify.

Connect

Add this server URL to your MCP client:

https://www.shiori.sh/mcp

Prefer the www URL — it matches the production site and OAuth resource metadata. https://shiori.sh/mcp also works: /mcp and /.well-known/* are served on both hosts without a redirect, so the protected-resource identifier matches whichever URL you configured.

Most MCP clients support "remote" or "URL-based" servers. Add the URL above, and the client will handle OAuth authentication automatically — you'll be prompted to authorize through your browser the first time you connect.

App setup

Claude Code

Run this command in your terminal:

claude mcp add shiori --transport http https://www.shiori.sh/mcp

Then restart Claude Code. You'll be prompted to authorize through your browser on first use.

Claude Desktop

Go to Settings → Integrations → Add MCP Server. Enter the URL https://www.shiori.sh/mcp and follow the OAuth prompts.

Cursor

Go to Cursor Settings → MCP → Add new MCP Server. Set the type to "URL" and enter https://www.shiori.sh/mcp. Dynamic registration accepts Cursor's cursor://anysphere.cursor-mcp/oauth/callback redirect.

Windsurf

Follow Windsurf's MCP configuration guide. Add a new server with URL https://www.shiori.sh/mcp.

Codex

Run this command in your terminal:

codex mcp add shiori --url https://www.shiori.sh/mcp

VS Code / Copilot

Add to your MCP settings (.vscode/mcp.json or user settings):

{
  "servers": {
    "shiori": {
      "type": "http",
      "url": "https://www.shiori.sh/mcp"
    }
  }
}

ChatGPT

Go to Settings → Connectors → Add Connector. Enter the URL https://www.shiori.sh/mcp, give it a name, and save. Then start a new conversation, click More → Add Connectors, and select Shiori. You'll be prompted to authorize on first use.

Other MCP clients

Any MCP client that supports remote/HTTP servers can connect. Use the server URL https://www.shiori.sh/mcp. The client will discover the OAuth configuration automatically via the .well-known/oauth-authorization-server metadata endpoint.

Approve access

The first connection opens Shiori in the browser. Sign in if needed and approve access. Do not paste an API key, token, or secret into the AI chat.

If the client must restart before it can load a new MCP server, restart it, then continue with Verify.

Verify

Call whoami. Do not treat MCP as connected until it returns the intended Shiori account.
Use search_links for topic or content questions. Use list_links only for metadata filters (unread, recent, by tag, favorites, trash).
Search for https://www.shiori.sh/docs/mcp (or the title "MCP") before saving. Reuse an existing item if present. Otherwise call save_link with that exact URL.
Call get_links with the saved link's id as a one-element array. Confirm the item is readable (title, URL, and content — or still processing).

Setup is complete only after whoami and a successful save_link / search_links / get_links round-trip.

Optional CLI

Prefer MCP. Fall back to the CLI only if this client cannot connect over MCP. Install with npm install -g @shiori-sh/cli. The CLI still authenticates with an API key today (shiori auth) — create the key in Settings → API keys and paste it into the CLI locally, never into chat. Confirm with shiori whoami.

Available tools

Tool	Description
search_links	Search your saved links by topic — hybrid semantic + keyword across titles, summaries, and content. Returns up to 20 results with a ~800-char snippet and `content_length` each
list_links	Browse saved links by date, read-status, favorites, or tag (metadata-only overview — not for topic search)
get_links	Fetch 1–5 links by ID. Default is full content. Prefer `content=none` (outline), then a bounded slice (`snippet` / `max_chars` / `section`), then `full`
save_link	Save a new URL to your collection (optionally with a custom saved date). On paid accounts, an X self-reply thread is saved completely and each post uses one advanced enrichment
save_markdown	Save markdown text with no URL. Use this when the user has text and no URL
update_link	Mark links as read/unread or favorite/unfavorite, edit title/summary/saved date, update markdown note content, or restore from trash
delete_link	Move a link to the trash
empty_trash	Permanently delete all trashed links
list_tags	List all your tags
create_tag	Create a new tag
update_tag	Rename a tag
delete_tag	Delete a tag (links are untagged, not deleted)
set_link_tags	Set the tags on a link
list_subscriptions	List your RSS/Atom feed subscriptions
add_subscription	Subscribe to a new RSS or Atom feed
remove_subscription	Unsubscribe from a feed
sync_subscription	Trigger an immediate feed sync
whoami	Get your profile and subscription info

Progressive reads

Agents should read saved articles in three steps instead of always pulling full bodies:

Overview — search_links (snippet + content_length) or list_links (metadata). Or get_links with content=none for publication metadata plus a markdown heading outline.
Slice — get_links with content=snippet (~800 chars), max_chars + offset to page, or section to extract one heading.
Full — get_links with content=full (the default, so existing clients keep working). Bodies are hard-capped; a truncated response includes next_offset so you can continue.

Never request full content for a whole search result set. Start from the snippet, then slice the one or two links that actually need more.

Agent skill

A published Shiori skill teaches agents to connect MCP, verify with whoami, and search or save links. Install it from the skill docs or fetch the file directly:

https://www.shiori.sh/.well-known/agent-skills/shiori/SKILL.md

Agents can also discover it at /.well-known/agent-skills/index.json or /llms.txt.