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

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.

Related MCP server: shiori-mcp

Configuration

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

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