linkwarden-mcp

An MCP server that wraps the Linkwarden bookmark API in a small set of token-frugal tools. Tool responses are compact plain text (#id name :: url) so listing collections or links costs as few tokens as possible.

Tools

Tool	What it does
list_collections	List collections as #id name (count).
list_links	List links as #id name :: url; optional collection_id, limit.
find_link	Check if a URL already exists (tracking params stripped first).
add_link	Add a link: strips tracking params, skips duplicates, then moves it into a collection.
move_link	Move an existing link to another collection.
delete_link	Delete a link by id.
create_collection	Create a new collection.

Behaviour baked in from experience

• Tracking params are stripped on add (utm_*, fbclid, gclid, gbraid, gad_source, gad_campaignid, rcm, …); meaningful params like variant and model are kept.
• Two-step create. Linkwarden ignores collectionId on link creation, so add_link POSTs the link then PUTs it into the target collection.
• Correct PUT shape. Updates always send id, url, collection.{id,ownerId} and tags, which the API requires.
• Full-list dedup. Linkwarden caps page size at ~50, so dedup walks every page via cursor pagination rather than trusting a single limit.

Configuration

Configuration comes from environment variables — no secret is ever hardcoded:

Variable	Required	Default	Notes
LINKWARDEN_URL	no	http://links.lan	Base URL, no /api/v1.
LINKWARDEN_TOKEN	yes	—	API token (Settings → Access Tokens). Secret.
LINKWARDEN_OWNER_ID	no	1	Owner id used when moving links.

How the token is stored: in production it is supplied by the MCP host via the server config's env block (see below) — it is not read from disk. For local development you may instead copy .env.example to .env and fill in the token; .env is git-ignored and loaded automatically. Host-provided env vars take precedence over .env.

Run

uv sync
uv run linkwarden-mcp   # serves over stdio

Register with an MCP host

Claude Code:

claude mcp add linkwarden -e LINKWARDEN_URL=http://links.lan -e LINKWARDEN_TOKEN=your-token -- uv --directory C:/Users/olive/Github/linkwarden-mcp run linkwarden-mcp

Or Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "linkwarden": {
      "command": "uv",
      "args": ["--directory", "C:/Users/olive/Github/linkwarden-mcp", "run", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_URL": "http://links.lan",
        "LINKWARDEN_TOKEN": "your-token"
      }
    }
  }
}

Development

uv run ruff check .   # lint
uv run ruff format .  # format
uv run ty check       # type check