{
"markdown": "# linkwarden-mcp\n\n\n\n[](https://github.com/ni-c/linkwarden-mcp/actions/workflows/ci.yml)\n[](https://scorecard.dev/viewer/?uri=github.com/ni-c/linkwarden-mcp)\n![\"Socket](\"https://socket.dev/api/badge/npm/package/linkwarden-mcp\")
\n[](https://glama.ai/mcp/servers/ni-c/linkwarden-mcp)\n
\n[](https://www.npmjs.com/package/linkwarden-mcp)\n[](https://github.com/ni-c/linkwarden-mcp/pkgs/container/linkwarden-mcp)\n[](https://mcp-hub.ni-c.de)\n
\n[](https://linkwarden-mcp.ni-c.de)\n[](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for\n[Linkwarden](https://linkwarden.app), the self-hosted bookmark manager that keeps a\npermanent copy of every page it saves.\n\nLets MCP clients like Claude Code, Claude Desktop or Codex search a bookmark\ncollection, organise it into collections and tags, and **read the preserved article\ntext of a saved page**, so a link that has been archived can be summarised or quoted\nwithout fetching the live site again.\n\nTwenty-eight tools is the ceiling, not the floor: `LINKWARDEN_ALLOW_TOOLS=essential`\nregisters a curated eight instead, and a model picks the right tool far more reliably\nfrom eight than from twenty-eight — see\n[choosing which tools load](#choosing-which-tools-load).\n\n\n\n\n\n \n \n ![\"An](\"https://linkwarden-mcp.ni-c.de/architecture.svg\")
\n\n\n> **Note:** Linkwarden's published API reference is incomplete. This server was\n> written against the routes in `apps/web/pages/api/v1/**` and the request schemas in\n> `packages/lib/schemaValidation.ts` of\n> [linkwarden/linkwarden](https://github.com/linkwarden/linkwarden), verified against\n> **v2.16.0** on 2026-08-17. Those two files are the source of truth for every tool\n> here.\n\n## What makes it different\n\n**Reads what Linkwarden preserved.** Linkwarden keeps a permanent copy of every\npage it saves. `get_link_content` serves that article text, so a saved link can be\nsummarised or quoted without fetching the live site again — and long articles are\nsliced, not dumped.\n\n**Organises without clobbering.** Linkwarden's update routes replace whole\nrecords. This server reads the current state and merges, so changing a title\nnever silently strips a link's tags or a collection's collaborators.\n\n**Output is an allowlist.** Linkwarden returns whole Prisma rows; every field in a\nresult here is named explicitly. Article text stays out of list results, collection\nmembers' names and e-mail addresses are dropped, and a column added by a future\nrelease cannot land in the model's context unannounced.\n\n## Requirements\n\n- Node.js ≥ 22\n- A running Linkwarden instance\n- An access token, created under **Settings → Access Tokens**\n\nLinkwarden has no per-token scopes: a token carries the full permissions of the\naccount that created it. Create a dedicated account with access only to the\ncollections this server should see rather than handing it an admin token.\n\n## Configuration\n\n| Variable | Required | Description |\n| ------------------------- | -------- | ---------------------------------------------------------------------------------- |\n| `LINKWARDEN_URL` | yes | Base URL, e.g. `https://links.example.net` (without `/api/v1`) |\n| `LINKWARDEN_TOKEN` | yes | Access token from Settings → Access Tokens |\n| `LINKWARDEN_READ_ONLY` | no | `true` registers only the read tools |\n| `LINKWARDEN_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |\n| `LINKWARDEN_DENY_TOOLS` | no | Same syntax; removed from whatever `LINKWARDEN_ALLOW_TOOLS` left |\n| `ELICITATION` | no | `false` replaces the approval dialog with the two-call token. **Not prefixed** |\n| `LINKWARDEN_INSECURE_TLS` | no | `true` accepts self-signed certificates (scoped to this connection) |\n\n> **Use `https://`.** Over plain http the token travels unencrypted; the server prints\n> a warning unless the host is local. For a self-signed certificate prefer a proper\n> internal CA over `LINKWARDEN_INSECURE_TLS`.\n\nThe token is removed from the process environment once it has been read, so it is not\nvisible to child processes or in `/proc//environ`.\n\nWithout credentials the server still starts and lists its tools, so registries and\ninspectors can introspect it; every call then fails with setup instructions instead of\nreaching the API.\n\n### Choosing which tools load\n\n`LINKWARDEN_ALLOW_TOOLS` and `LINKWARDEN_DENY_TOOLS` take comma-separated tool names;\na trailing `*` matches a whole family. `essential` is a curated preset of eight —\nsave, find and read — marked as such in the\n[tool reference](https://linkwarden-mcp.ni-c.de/reference/tools).\n\n```sh\nLINKWARDEN_ALLOW_TOOLS=essential\nLINKWARDEN_ALLOW_TOOLS=search_links,get_link_content,create_link\nLINKWARDEN_DENY_TOOLS=bulk_*\n```\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot silently\nhide a tool — an absent tool is not something anyone traces back to an environment\nvariable. A filtered tool is never registered, so it is absent from `tools/list` and\nunknown to `tools/call` alike, exactly like a write tool under `LINKWARDEN_READ_ONLY`.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de) is the\nother answer — its `/hub` endpoint replaces every server's tools with six meta-tools.\n\n## Installation\n\n### Claude Code\n\n```sh\nclaude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp\n```\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"linkwarden\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"linkwarden-mcp\"],\n \"env\": {\n \"LINKWARDEN_URL\": \"https://links.example.net\",\n \"LINKWARDEN_TOKEN\": \"…\"\n }\n }\n }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.linkwarden]\ncommand = \"npx\"\nargs = [\"-y\", \"linkwarden-mcp\"]\nenv = { LINKWARDEN_URL = \"https://links.example.net\", LINKWARDEN_TOKEN = \"…\" }\n```\n\n### From source\n\n```sh\nnpm install && npm run build\nLINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js\n```\n\n### Docker\n\n```sh\ndocker build -t linkwarden-mcp .\ndocker run --rm -i \\\n -e LINKWARDEN_URL=https://links.example.net \\\n -e LINKWARDEN_TOKEN=… \\\n linkwarden-mcp\n```\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches linkwarden-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"linkwarden\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"linkwarden-mcp\"],\n \"env\": {\n \"LINKWARDEN_URL\": \"https://links.example.net\",\n \"LINKWARDEN_TOKEN\": \"…\",\n \"LINKWARDEN_ALLOW_TOOLS\": \"essential\"\n },\n \"denyTools\": [\"bulk_*\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://linkwarden-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose.\nSeven tools that answered with a sentence — _\"Link 42 deleted.\"_ — now answer\nwith the fields as well, and the sentence stays in the text block.\n\nThe ten reading tools carry `untrusted: true` and `source: \"linkwarden\"` as\nfields. Bookmark titles, descriptions and above all the preserved article text\nare written by whoever controls the target site; this server has always said so\nin `notes`, which is prose a client can read but not check, and the field is\nwhat makes it checkable. The write tools are without it: they report an id this\nserver was given and a count it made.\n\nAn over-budget result still drops list entries, and an oversized untrusted\nenvelope still loses characters from its largest field. Where neither leaves\nanything to give it is now an **error** rather than an envelope carrying the\noversized document as a string: that envelope is valid JSON and not a valid\nanswer, since the SDK checks a result against the schema its tool declares.\n\n### Reading\n\n| Tool | Description |\n| ------------------------ | -------------------------------------------------------------------------------------------------------- |\n| `search_links` | Search or list bookmarks. Supports Linkwarden's field filters (`tag:`, `collection:`, `before:`, `!` …). |\n| `get_link` | One bookmark with its tags, collection and which preserved formats exist. |\n| `get_link_content` | The preserved article text of a saved page, sliced for long articles. |\n| `list_collections` | All collections with link counts; nesting via `parentId`. |\n| `get_collection` | One collection with its per-member permissions. |\n| `list_tags` | Tags with link counts and their per-tag archival settings. |\n| `get_tag` | One tag. |\n| `get_dashboard` | Recently added plus pinned links, as Linkwarden's dashboard shows them. |\n| `list_rss_subscriptions` | The RSS feeds this account subscribes to. |\n| `get_current_user` | Which account the token belongs to, and its archival defaults. Good connectivity check. |\n| `get_worker_stats` | Preservation and search-index queue. **Administrator account only** — everyone else gets HTTP 403. |\n\n### Writing\n\nNot registered at all when `LINKWARDEN_READ_ONLY=true`. Tools marked 👤 **ask a\nperson** through MCP elicitation — a dialog the model cannot answer on its behalf —\nand fall back to a two-call `confirm_token` where the client cannot show one. See\n[Asking a person](https://linkwarden-mcp.ni-c.de/guide/approval).\n\n| Tool | Description |\n| ------------------------------ | ---------------------------------------------------------------------------- |\n| `create_link` | Save a bookmark, optionally with tags and a collection (created on demand). |\n| `update_link` | Change title, description, tags or collection. 👤 only when the URL changes. |\n| `set_link_pinned` | Pin or unpin a link for this account. |\n| `delete_link` 👤 | Delete a bookmark and its preserved copies. |\n| `bulk_update_links` 👤 | Apply one tag list and/or collection to many links. |\n| `bulk_delete_links` 👤 | Delete many bookmarks at once. |\n| `represerve_link` 👤 | Drop the existing archives and preserve the page again. |\n| `delete_link_preservations` 👤 | Drop the archives of several links, keeping the bookmarks. |\n| `create_collection` | Create a collection, optionally nested. |\n| `update_collection` | Rename, re-parent or publish a collection. 👤 only when publishing. |\n| `delete_collection` 👤 | Delete a collection — cascades to its links and sub-collections. |\n| `create_tags` | Create tags or change their archival settings (upsert by name). |\n| `rename_tag` 👤 | Rename a tag — every link that carries it follows. |\n| `delete_tags` 👤 | Delete tags; the links keep existing. |\n| `merge_tags` 👤 | Fold several tags into one new tag. |\n| `create_rss_subscription` | Subscribe to an RSS/Atom feed. |\n| `delete_rss_subscription` 👤 | Stop polling a feed. |\n\n## Not exposed, on purpose\n\n- **Access-token management** (`/tokens`). A tool that can mint API credentials is a\n privilege-escalation surface, and a bookmark server has no business holding one.\n- **User administration** (`/users`, account deletion). Out of scope.\n- **Backup export and import** (`/migration`). The export dumps the whole instance\n into the model's context; the import can destroy it.\n- **Highlights.** Creating one needs exact character offsets into the preserved\n document, which a model cannot produce meaningfully, and Linkwarden offers no route\n to list existing highlights.\n- **Archive uploads** and the signed `preserved` URLs, which need\n `NEXT_PUBLIC_USER_CONTENT_DOMAIN` to be configured.\n- The deprecated `GET /links` listing route — `search_links` uses `GET /search`\n instead, which is what Linkwarden itself recommends.\n\n## Safety\n\n- **Destructive tools ask a person.** Where the client supports MCP elicitation they\n raise a real dialog that the model cannot answer on its behalf. Where it does not,\n the first call returns a short-lived token bound to the exact target and only a\n second call carrying it performs the operation — which proves the call was made\n twice with the same arguments and nothing more, and the text says so. An approval\n issued for one link, tag set or change cannot be replayed for another.\n `ELICITATION=false` takes that fallback deliberately; it never removes the guard.\n- **Losing something is not only deletion.** Publishing a collection, changing a\n link's URL — which deletes every preserved copy of the old page — and renaming a\n tag, which follows every link that carries it, are all asked about.\n- **Confirmation prompts never quote content from Linkwarden.** Titles, URLs,\n descriptions and collection names come from saved pages and from other users of the\n instance; only counts and ids appear in the text a model reads.\n- **Bookmarked URLs are checked before Linkwarden fetches them.** `create_link`,\n `update_link` and `create_rss_subscription` hand a URL to a server that opens it\n in a headless browser — and `get_link_content` reads the result back, which makes\n an unchecked URL a way to read from inside Linkwarden's network. Loopback and\n link-local addresses, including the cloud metadata endpoints and their hostnames,\n are refused; addresses are compared numerically, so an IPv4-mapped literal such as\n `[::ffff:169.254.169.254]` is caught too, and a hostname is resolved before it is\n accepted. Private LAN addresses stay allowed — bookmarking the router's interface\n or an intranet page is a normal thing to do with a self-hosted bookmark manager,\n which also means a container beside Linkwarden is reachable; SECURITY.md says what\n the check does and does not cover, including the entries inside an RSS feed.\n- **Returned content is marked as untrusted data**, in particular the preserved\n article text, which is written by whoever controls the target site.\n- **Partial updates never clear fields.** Linkwarden's update routes replace the whole\n record, so this server reads the current state and merges — otherwise an update\n would silently strip a link's tags or a collection's collaborators.\n- **A 200 is not trusted on its own.** Several Linkwarden routes report failures with\n HTTP 200 and an error sentence in the body, and a route without a handler for the\n method used answers 200 with nothing at all. Both are reported as errors rather than\n as a successful write.\n- Error bodies are truncated, HTML error pages are dropped entirely, redirects are\n never followed (so the bearer token cannot be replayed to another host), and every\n request carries a timeout.\n- `LINKWARDEN_READ_ONLY=true` does not register the write tools at all.\n- **Residual risk:** within the permissions of the token you configure, a model that\n is asked to do something destructive and is confirmed by a user can still do it.\n Scope the account, and keep host-level permission prompts on.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[linkwarden-mcp.ni-c.de](https://linkwarden-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```sh\nnpm install\nnpm run build\nnpm test\nnpm run test:coverage\nnpm run lint\nnpm run format\nnpm run docs:tools # regenerate docs/reference/tools.md from the registered tools\n```\n\n`docs/reference/tools.md` is generated; CI fails if the committed copy no longer\nmatches the code. The documentation site lives in `docs/` with **its own**\n`package.json` and lockfile — VitePress must not end up in the root install, which runs\nin the Docker build and across the whole test matrix.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Releasing\n\nEverything is driven by a tag; there is no manual publish step.\n\n1. Move the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) to the new version\n and date it. The release workflow extracts that section with `awk`, so the\n `## [x.y.z]` heading shape matters.\n2. Bump `version` in `package.json`.\n3. `npm run lint && npm run build && npm run test:coverage`.\n4. Commit, then a **signed annotated** tag:\n\n ```sh\n git tag -s v0.1.1 -m \"v0.1.1\"\n git push origin main v0.1.1\n ```\n\n`release.yml` then verifies the tag matches `package.json`, publishes to npm over\n**Trusted Publishing** (OIDC — no npm token exists to leak) with provenance, syncs the\nversion into both `server.json` package entries, publishes to the MCP registry, and\ncuts the GitHub release from the changelog section. `ci.yml` pushes the multi-arch\ncontainer image to GHCR in parallel.\n\nIf the registry step fails, fix it on `main` and run the `mcp-registry.yml` workflow by\nhand. Re-running the failed job is not an option: it checks out the immutable tag, so a\nfix on `main` could never reach it.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/linkwarden-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n",
"bytes": 21017,
"sha": "ef779500fc6af293037b73781444fba827d103ade5a8686b711aa299e1ffb133",
"repo_slug": "ni-c/linkwarden-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_linkwarden_mcp_7422821c/readme"
}