# linkwarden-mcp
[](https://github.com/ni-c/linkwarden-mcp/actions/workflows/ci.yml)
[](https://scorecard.dev/viewer/?uri=github.com/ni-c/linkwarden-mcp)
[](https://socket.dev/npm/package/linkwarden-mcp)
[](https://glama.ai/mcp/servers/ni-c/linkwarden-mcp)
[](https://www.npmjs.com/package/linkwarden-mcp)
[](https://github.com/ni-c/linkwarden-mcp/pkgs/container/linkwarden-mcp)
[](https://mcp-hub.ni-c.de)
[](https://linkwarden-mcp.ni-c.de)
[](https://github.com/sponsors/ni-c)
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[Linkwarden](https://linkwarden.app), 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](#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](https://github.com/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
| Variable | Required | Description |
| ------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `LINKWARDEN_URL` | yes | Base URL, e.g. `https://links.example.net` (without `/api/v1`) |
| `LINKWARDEN_TOKEN` | yes | Access token from Settings → Access Tokens |
| `LINKWARDEN_READ_ONLY` | no | `true` registers only the read tools |
| `LINKWARDEN_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |
| `LINKWARDEN_DENY_TOOLS` | no | Same syntax; removed from whatever `LINKWARDEN_ALLOW_TOOLS` left |
| `ELICITATION` | no | `false` replaces the approval dialog with the two-call token. **Not prefixed** |
| `LINKWARDEN_INSECURE_TLS` | no | `true` accepts self-signed certificates (scoped to this connection) |
> **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](https://linkwarden-mcp.ni-c.de/reference/tools).
```sh
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](https://mcp-hub.ni-c.de) is the
other answer — its `/hub` endpoint replaces every server's tools with six meta-tools.
## Installation
### Claude Code
```sh
claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp
```
### Claude Desktop
```json
{
"mcpServers": {
"linkwarden": {
"command": "npx",
"args": ["-y", "linkwarden-mcp"],
"env": {
"LINKWARDEN_URL": "https://links.example.net",
"LINKWARDEN_TOKEN": "…"
}
}
}
}
```
### Codex
```toml
[mcp_servers.linkwarden]
command = "npx"
args = ["-y", "linkwarden-mcp"]
env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }
```
### From source
```sh
npm install && npm run build
LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js
```
### Docker
```sh
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](https://mcp-hub.ni-c.de): 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:
```json
{
"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](https://linkwarden-mcp.ni-c.de/guide/clients#through-mcp-hub).
## 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
| Tool | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
| `search_links` | Search or list bookmarks. Supports Linkwarden's field filters (`tag:`, `collection:`, `before:`, `!` …). |
| `get_link` | One bookmark with its tags, collection and which preserved formats exist. |
| `get_link_content` | The preserved article text of a saved page, sliced for long articles. |
| `list_collections` | All collections with link counts; nesting via `parentId`. |
| `get_collection` | One collection with its per-member permissions. |
| `list_tags` | Tags with link counts and their per-tag archival settings. |
| `get_tag` | One tag. |
| `get_dashboard` | Recently added plus pinned links, as Linkwarden's dashboard shows them. |
| `list_rss_subscriptions` | The RSS feeds this account subscribes to. |
| `get_current_user` | Which account the token belongs to, and its archival defaults. Good connectivity check. |
| `get_worker_stats` | Preservation and search-index queue. **Administrator account only** — everyone else gets HTTP 403. |
### 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](https://linkwarden-mcp.ni-c.de/guide/approval).
| Tool | Description |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `create_link` | Save a bookmark, optionally with tags and a collection (created on demand). |
| `update_link` | Change title, description, tags or collection. 👤 only when the URL changes. |
| `set_link_pinned` | Pin or unpin a link for this account. |
| `delete_link` 👤 | Delete a bookmark and its preserved copies. |
| `bulk_update_links` 👤 | Apply one tag list and/or collection to many links. |
| `bulk_delete_links` 👤 | Delete many bookmarks at once. |
| `represerve_link` 👤 | Drop the existing archives and preserve the page again. |
| `delete_link_preservations` 👤 | Drop the archives of several links, keeping the bookmarks. |
| `create_collection` | Create a collection, optionally nested. |
| `update_collection` | Rename, re-parent or publish a collection. 👤 only when publishing. |
| `delete_collection` 👤 | Delete a collection — cascades to its links and sub-collections. |
| `create_tags` | Create tags or change their archival settings (upsert by name). |
| `rename_tag` 👤 | Rename a tag — every link that carries it follows. |
| `delete_tags` 👤 | Delete tags; the links keep existing. |
| `merge_tags` 👤 | Fold several tags into one new tag. |
| `create_rss_subscription` | Subscribe to an RSS/Atom feed. |
| `delete_rss_subscription` 👤 | Stop polling a feed. |
## 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](https://linkwarden-mcp.ni-c.de)** (source in [`docs/`](docs/)).
## Development
```sh
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](CONTRIBUTING.md).
## Releasing
Everything is driven by a tag; there is no manual publish step.
1. Move the `[Unreleased]` section of [CHANGELOG.md](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:
```sh
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](CONTRIBUTING.md). For vulnerabilities please use
[private reporting](https://github.com/ni-c/linkwarden-mcp/security/advisories/new)
rather than a public issue; the policy is in [SECURITY.md](SECURITY.md).
## License
[MIT](LICENSE) © Willi Thiel