linkwarden-mcp

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

It lets an MCP client — Claude Code, Claude Desktop, 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.

📖 Full documentation at linkwarden-mcp.ni-c.de

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.

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.

Related MCP server: linkwarden-mcp

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.

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

Tools

Reading

Writing

Not registered at all when LINKWARDEN_READ_ONLY=true. Tools marked 🔒 require a confirmation token.

Deliberately not exposed

• 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 are two-step. The first call returns a short-lived confirmation token bound to the exact target; only a second call carrying that token performs the operation. A model cannot satisfy this gate on its own, and a token issued for one link, tag set or change cannot be replayed for another.

• Widening visibility counts as destructive. Publishing a collection and changing a link's URL — which deletes every preserved copy of the old page — both need a confirmation, not just deletions.

• 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.

• 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.

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.

License

MIT © Willi Thiel