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 ≥ 22
• 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/<pid>/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

Writing

Not registered at all when LINKWARDEN_READ_ONLY=true. Tools marked 👤 ask a person through MCP elicitation — a dialog the model cannot answer on its behalf — and fall back to a two-call confirm_token where the client cannot show one. See Asking a person.

Not exposed, on purpose

• Access-token management (/tokens). A tool that can mint API credentials is a privilege-escalation surface, and a bookmark server has no business holding one.
• User administration (/users, account deletion). Out of scope.
• Backup export and import (/migration). The export dumps the whole instance into the model's context; the import can destroy it.
• Highlights. Creating one needs exact character offsets into the preserved document, which a model cannot produce meaningfully, and Linkwarden offers no route to list existing highlights.
• Archive uploads and the signed preserved URLs, which need NEXT_PUBLIC_USER_CONTENT_DOMAIN to be configured.
• The deprecated GET /links listing route — search_links uses GET /search instead, which is what Linkwarden itself recommends.

Safety

• Destructive tools ask a person. Where the client supports MCP elicitation they raise a real dialog that the model cannot answer on its behalf. Where it does not, the first call returns a short-lived token bound to the exact target and only a second call carrying it performs the operation — which proves the call was made twice with the same arguments and nothing more, and the text says so. An approval issued for one link, tag set or change cannot be replayed for another. ELICITATION=false takes that fallback deliberately; it never removes the guard.
• Losing something is not only deletion. Publishing a collection, changing a link's URL — which deletes every preserved copy of the old page — and renaming a tag, which follows every link that carries it, are all asked about.
• Confirmation prompts never quote content from Linkwarden. Titles, URLs, descriptions and collection names come from saved pages and from other users of the instance; only counts and ids appear in the text a model reads.
• Bookmarked URLs are checked before Linkwarden fetches them. create_link, update_link and create_rss_subscription hand a URL to a server that opens it in a headless browser — and get_link_content reads the result back, which makes an unchecked URL a way to read from inside Linkwarden's network. Loopback and link-local addresses, including the cloud metadata endpoints and their hostnames, are refused; addresses are compared numerically, so an IPv4-mapped literal such as [::ffff:169.254.169.254] is caught too, and a hostname is resolved before it is accepted. Private LAN addresses stay allowed — bookmarking the router's interface or an intranet page is a normal thing to do with a self-hosted bookmark manager, which also means a container beside Linkwarden is reachable; SECURITY.md says what the check does and does not cover, including the entries inside an RSS feed.
• Returned content is marked as untrusted data, in particular the preserved article text, which is written by whoever controls the target site.
• Partial updates never clear fields. Linkwarden's update routes replace the whole record, so this server reads the current state and merges — otherwise an update would silently strip a link's tags or a collection's collaborators.
• A 200 is not trusted on its own. Several Linkwarden routes report failures with HTTP 200 and an error sentence in the body, and a route without a handler for the method used answers 200 with nothing at all. Both are reported as errors rather than as a successful write.
• Error bodies are truncated, HTML error pages are dropped entirely, redirects are never followed (so the bearer token cannot be replayed to another host), and every request carries a timeout.
• LINKWARDEN_READ_ONLY=true does not register the write tools at all.
• Residual risk: within the permissions of the token you configure, a model that is asked to do something destructive and is confirmed by a user can still do it. Scope the account, and keep host-level permission prompts on.

Documentation

The full guide, tool reference and security notes live at linkwarden-mcp.ni-c.de (source in docs/).

Development

npm install
npm run build
npm test
npm run test:coverage
npm run lint
npm run format
npm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md is generated; CI fails if the committed copy no longer matches the code. The documentation site lives in docs/ with its own package.json and lockfile — VitePress must not end up in the root install, which runs in the Docker build and across the whole test matrix.

See CONTRIBUTING.md.

Releasing

Everything is driven by a tag; there is no manual publish step.

1. Move the [Unreleased] section of CHANGELOG.md to the new version and date it. The release workflow extracts that section with awk, so the ## [x.y.z] heading shape matters.

2. Bump version in package.json.

3. npm run lint && npm run build && npm run test:coverage.

4. Commit, then a signed annotated tag:

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1
   

release.yml then verifies the tag matches package.json, publishes to npm over Trusted Publishing (OIDC — no npm token exists to leak) with provenance, syncs the version into both server.json package entries, publishes to the MCP registry, and cuts the GitHub release from the changelog section. ci.yml pushes the multi-arch container image to GHCR in parallel.

If the registry step fails, fix it on main and run the mcp-registry.yml workflow by hand. Re-running the failed job is not an option: it checks out the immutable tag, so a fix on main could never reach it.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel