linkwarden-mcp

# linkwarden-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/linkwarden-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/linkwarden-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/linkwarden-mcp)](https://www.npmjs.com/package/linkwarden-mcp)
[![downloads](https://img.shields.io/npm/dm/linkwarden-mcp)](https://www.npmjs.com/package/linkwarden-mcp)
[![container](https://img.shields.io/badge/ghcr.io-linkwarden--mcp-blue?logo=docker&logoColor=white)](https://github.com/ni-c/linkwarden-mcp/pkgs/container/linkwarden-mcp)
[![node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](https://nodejs.org)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![docs](https://img.shields.io/badge/docs-linkwarden--mcp.ni--c.de-4f46e5)](https://linkwarden-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)

A [Model Context Protocol](https://modelcontextprotocol.io) server for
[Linkwarden](https://linkwarden.app), 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](https://linkwarden-mcp.ni-c.de)**

![Demo](https://linkwarden-mcp.ni-c.de/demo.gif)

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, which is why that
     fallback brings its own dark card instead of relying on a media query. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://linkwarden-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://linkwarden-mcp.ni-c.de/architecture-light.svg">
  <img src="https://linkwarden-mcp.ni-c.de/architecture.svg" alt="An MCP client speaks stdio to linkwarden-mcp, which calls the Linkwarden REST API over HTTPS; Linkwarden stores bookmarks and preserved copies of pages" width="800">
</picture>

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

## 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_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/<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

```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
```

## Tools

### 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 🔒 require a
confirmation token.

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

### 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 `pre