Linkwarden

linkwarden-mcp

A Model Context Protocol (MCP) server for Linkwarden, the self-hosted bookmark manager that keeps a permanent copy of every page it saves.

Lets MCP clients like Claude Code, Claude Desktop or Codex search a bookmark collection, organise it into collections and tags, and read the preserved article text of a saved page, so a link that has been archived can be summarised or quoted without fetching the live site again.

Twenty-eight tools is the ceiling, not the floor: LINKWARDEN_ALLOW_TOOLS=essential registers a curated eight instead, and a model picks the right tool far more reliably from eight than from twenty-eight — see choosing which tools load.

Note: Linkwarden's published API reference is incomplete. This server was

written against the routes in apps/web/pages/api/v1/** and the request schemas in

packages/lib/schemaValidation.ts of

linkwarden/linkwarden, verified against

v2.16.0 on 2026-08-17. Those two files are the source of truth for every tool

here.

What makes it different

Reads what Linkwarden preserved. Linkwarden keeps a permanent copy of every page it saves. get_link_content serves that article text, so a saved link can be summarised or quoted without fetching the live site again — and long articles are sliced, not dumped.

Organises without clobbering. Linkwarden's update routes replace whole records. This server reads the current state and merges, so changing a title never silently strips a link's tags or a collection's collaborators.

Output is an allowlist. Linkwarden returns whole Prisma rows; every field in a result here is named explicitly. Article text stays out of list results, collection members' names and e-mail addresses are dropped, and a column added by a future release cannot land in the model's context unannounced.

Requirements

• Node.js ≥ 24
• A running Linkwarden instance
• An access token, created under Settings → Access Tokens

Linkwarden has no per-token scopes: a token carries the full permissions of the account that created it. Create a dedicated account with access only to the collections this server should see rather than handing it an admin token.

Configuration

Use `https://`. Over plain http the token travels unencrypted; the server prints

a warning unless the host is local. For a self-signed certificate prefer a proper

internal CA over LINKWARDEN_INSECURE_TLS.

The token is removed from the process environment once it has been read, so it is not visible to child processes or in /proc/ /environ.

Without credentials the server still starts and lists its tools, so registries and inspectors can introspect it; every call then fails with setup instructions instead of reaching the API.

Choosing which tools load

LINKWARDEN_ALLOW_TOOLS and LINKWARDEN_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of eight — save, find and read — marked as such in the tool reference.

LINKWARDEN_ALLOW_TOOLS=essential

LINKWARDEN_ALLOW_TOOLS=search_links,get_link_content,create_link LINKWARDEN_DENY_TOOLS=bulk_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under LINKWARDEN_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp

Claude Desktop

{

"mcpServers": { "linkwarden": { "command": "npx", "args": ["-y", "linkwarden-mcp"], "env": { "LINKWARDEN_URL": "https://links.example.net", "LINKWARDEN_TOKEN": "…" } } } }

Codex

[mcp_servers.linkwarden]

command = "npx" args = ["-y", "linkwarden-mcp"] env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }

From source

npm install && npm run build

LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js

Docker

docker build -t linkwarden-mcp .

docker run --rm -i \ -e LINKWARDEN_URL=https://links.example.net \ -e LINKWARDEN_TOKEN=… \ linkwarden-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches linkwarden-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "linkwarden": { "command": "npx", "args": ["-y", "linkwarden-mcp"], "env": { "LINKWARDEN_URL": "https://links.example.net", "LINKWARDEN_TOKEN": "…", "LINKWARDEN_ALLOW_TOOLS": "essential" }, "denyTools": ["bulk_*"] } } }

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose. Seven tools that answered with a sentence — _"Link 42 deleted."_ — now answer with the fields as well, and the sentence stays in the text block.

The ten reading tools carry untrusted: true and source: "linkwarden" as fields. Bookmark titles, descriptions and above all the preserved article text are written by whoever controls the target site; this server has always said so in notes, which is prose a client can read but not check, and the field is what makes it checkable. The write tools are without it: they report an id this server was given and a count it made.

An over-budget result still drops list entries, and an oversized untrusted envelope still loses characters from its largest field. Where neither leaves anything to give it is now an error rather than an envelope carrying the oversized document as a string: that envelope is valid JSON and not a valid answer, since the SDK checks a result against the schema its tool declares.

Reading

| list_rss_subscriptions | The RSS feeds this account subscribes to.