linkwarden-mcp

<p align="center">
  <a href="https://linkwarden.app/">
    <img src="docs/linkwarden-icon.svg" alt="Linkwarden" width="72" height="72">
  </a>
</p>

# linkwarden-mcp

<!-- mcp-name: io.github.flumpiey/linkwarden-mcp -->

**MCP server for self-hosted [Linkwarden](https://linkwarden.app/): ask your AI about bookmarks, collections, and tags.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io/)
[![CI](https://github.com/flumpiey/linkwarden-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/flumpiey/linkwarden-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/linkwarden-mcp.svg)](https://pypi.org/project/linkwarden-mcp/)

## What is Linkwarden?

[Linkwarden](https://linkwarden.app/) is a self-hosted, open-source bookmark manager. You collect, organize, annotate, and preserve webpages in one place, with full-page archives so content stays readable after the original page disappears. It also supports collaboration and public sharing.

This project wires the Linkwarden HTTP API into the [Model Context Protocol](https://modelcontextprotocol.io/) so Cursor, Claude, VS Code Copilot, and other MCP hosts can query your live library in natural language.

Useful Linkwarden links:

- [Documentation](https://docs.linkwarden.app/)
- [GitHub](https://github.com/linkwarden/linkwarden)
- [Cloud](https://linkwarden.app/)
- [Demo](https://demo.linkwarden.app/)
- [Self-hosting setup](https://docs.linkwarden.app/self-hosting/installation)

## What this server does

Default is **read-only**. You get:

- **18 read tools** - discovery (`list_resources`), six core reads (search, get, preserved content, collections, tags, overview), and eleven triage/hygiene workflows
- **Task tools (opt-in)** - intent-shaped writes such as `save_link`, `smart_save_link`, `organise_links`, `create_collection`, `apply_triage_plan` (register when matching write scopes are set)
- **Delete tools (opt-in)** - `delete_links`, `delete_tags`, `merge_tags`, `delete_collection` (register only under delete scopes; never implied by write)
- **Hard denylist** - tokens, session, auth, user admin (except `GET /api/v1/users/me`), migration, and whole-instance preservation stay blocked even when writes are on

Transport is **stdio**. No HTTP server. No global install required if you use [`uv`](https://docs.astral.sh/uv/) / `uvx`.

## Branding / icons

Four surfaces (keep them in sync when the mark changes):

1. **stdio hosts (Cursor, Claude Desktop via `mcp.json`):** `serverInfo.icons` from [`server_icons()`](src/linkwarden_mcp/server.py) — embedded data URI from [`src/linkwarden_mcp/assets/icon.png`](src/linkwarden_mcp/assets/icon.png), plus HTTPS fallback [`docs/icon-512.png`](docs/icon-512.png) (`https://raw.githubusercontent.com/flumpiey/linkwarden-mcp/main/docs/icon-512.png`). `website_url` is `https://linkwarden.app/`.
2. **Cursor plugin:** [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) `logo` → [`docs/linkwarden-icon.svg`](docs/linkwarden-icon.svg).
3. **Claude Desktop Extension:** [`mcpb/icon.png`](mcpb/icon.png) (packed with `npx @anthropic-ai/mcpb pack mcpb`).
4. **Claude.ai remote connectors:** Claude.ai ignores `serverInfo.icons` and uses the **root-domain favicon** of the connector URL. If you host a remote MCP later, serve [`docs/favicon.ico`](docs/favicon.ico) at the registrable domain root (e.g. `https://acme.com/favicon.ico` for `https://mcp.acme.com/...`).

[`server.json`](server.json) registry metadata also points its `icons[0].src` at the same raw `docs/icon-512.png` URL.

## Requirements

- Python ≥ 3.10 (pulled in automatically by `uvx`)
- [uv](https://docs.astral.sh/uv/) (provides `uvx`)
- A reachable Linkwarden instance: `LINKWARDEN_API_URL` + `LINKWARDEN_API_KEY`

### Access token

1. Sign in to your Linkwarden instance (self-hosted or Cloud).
2. Open **Settings → Access Tokens** (or go to `/settings/access-tokens`).
3. Create a **New Access Token**, give it a name, and copy the value into `LINKWARDEN_API_KEY`.
4. Set `LINKWARDEN_API_URL` to your instance base URL (usually without `/api/v1`; include `/api/v1` only if your deployment requires it), e.g. `https://links.example.com` or local Docker `http://127.0.0.1:3000`.

`linkwarden-mcp` sends the token as `Authorization: Bearer …`. API overview: [API Introduction](https://docs.linkwarden.app/api/api-introduction).

Copy [`.env.example`](.env.example) to `.env` for local runs — **never commit `.env`**. Prefer the Cursor plugin **Configure** UI for credentials, or a secret manager in production.

## Quick start

Run the [PyPI](https://pypi.org/project/linkwarden-mcp/) package with [`uvx`](https://docs.astral.sh/uv/guides/tools/):

```bash
uvx linkwarden-mcp
```

Paste a client config below, set `LINKWARDEN_API_URL` / `LINKWARDEN_API_KEY`, restart the host, then ask: *“Find my unread bookmarks about Python”* or *“What's in my Dev collection?”*

From a git clone (dev): `uvx --from git+https://github.com/flumpiey/linkwarden-mcp linkwarden-mcp` or `uv run --directory /path/to/linkwarden-mcp linkwarden-mcp`.

## Installation

Configs below pull [`linkwarden-mcp`](https://pypi.org/project/linkwarden-mcp/) from PyPI. Leave write-scope env vars unset for read-only.

<details>
<summary><strong>Cursor</strong></summary>

**Plugin (Configure UI for URL, key, and scopes):** this repo is a Cursor plugin via [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) + root [`mcp.json`](mcp.json).

1. Symlink or copy the clone to `~/.cursor/plugins/local/linkwarden-mcp` (Windows: `%USERPROFILE%\.cursor\plugins\local\linkwarden-mcp`).
   - **macOS / Linux:** `ln -s /path/to/linkwarden-mcp ~/.cursor/plugins/local/linkwarden-mcp`
   - **Windows:** Cursor does **not** follow symlinks for local plugins. Use a junction or copy instead:
     ```bat
     mklink /J "%USERPROFILE%\.cursor\plugins\local\linkwarden-mcp" "E:\Development\linkwarden-mcp"
     ```
     or:
     ```bat
     robocopy "E:\Development\linkwarden-mcp" "%USERPROFILE%\.cursor\plugins\local\linkwarden-mcp" /E
     ```
2. Reload the window.
3. Open **Plugins → Configure** on `linkwarden-mcp`. Set **Linkwarden API URL** and **Linkwarden API key**. Leave **Write scopes** / **Delete scopes** empty for read-only, or paste a CSV such as `links,collections`.
4. Confirm the `linkwarden` MCP server is enabled under Customize / MCP.

Marketplace listing is a separate submit at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish).

**Manual `mcp.json`:** project [`.cursor/mcp.json`](.cursor/mcp.json) or user-wide `~/.cursor/mcp.json`. Root [`mcp.json`](mcp.json) is plugin wiring with `${…}` placeholders only — never commit real secrets there.

From PyPI:

```json
{
  "mcpServers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}
```

Local editable (dev):

```json
{
  "mcpServers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/linkwarden-mcp", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}
```

Optional scoped writes in the `env` block:

```json
"LINKWARDEN_MCP_WRITE_SCOPES": "links,collections",
"LINKWARDEN_MCP_DELETE_SCOPES": "links"
```

Restart Cursor after saving. Confirm `linkwarden` under MCP settings.

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

**Desktop Extension (`.mcpb`):** download [`mcpb.mcpb`](https://github.com/flumpiey/linkwarden-mcp/releases/latest/download/mcpb.mcpb) from [GitHub Releases](https://github.com/flumpiey/linkwarden-mcp/releases). Use **v0.1.4+** (needs [`uv`](https://docs.astral.sh/uv/) on PATH). Launch is `uv tool run --python 3.12 linkwarden-mcp`. Do not put the PyPI package in `mcpb/pyproject.toml` dependencies — Claude Desktop syncs that file at install and can fail on system Python 3.13.

1. Open Claude Desktop → **Settings → Extensions**.
2. Open **Advanced settings** → **Install Extension…**
3. Select `mcpb.mcpb`. Review permissions, enter **Linkwarden API URL** and **Linkwarden API key**, then click **Install**.
4. Leave **Write scopes** and **Delete scopes** empty for read-only.
5. Restart Claude Desktop if tools do not appear.

Build your own bundle from a clone:

```bash
npx @anthropic-ai/mcpb pack mcpb
```

On Windows, double-click often does nothing and dragging the file into chat attaches it to the conversation instead of installing it. Use **Install Extension…** in Settings.

**Manual `claude_desktop_config.json` fallback:** edit the Claude Desktop config, then restart the app.

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}
```

Local clone:

```json
{
  "mcpServers": {
    "linkwarden": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/linkwarden-mcp", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}
```

</details>

<details>
<summary><strong>Claude Code</strong></summary>

Add via CLI:

```bash
claude mcp add linkwarden --env LINKWARDEN_API_URL=https://links.example.com --env LINKWARDEN_API_KEY=your-token -- uvx linkwarden-mcp
```

Or edit `~/.claude.json` / project MCP