# linkding-mcp

An [MCP](https://modelcontextprotocol.io) server for **[Linkding](https://linkding.link)**
bookmarks and web archival, designed to work as a
[claude.ai / Claude Desktop custom connector](https://support.claude.com/en/articles/11175166)
— so Claude can search, add, tag, archive, and delete your bookmarks (and inspect
their archival snapshots) from the web or desktop app.

Talks to Linkding's REST API with a personal API token. Targets Linkding v1.31+
(token auth, limit/offset pagination, assets API for HTML snapshots). Built with
[FastMCP](https://gofastmcp.com); authentication uses GitHub OAuth via FastMCP's
OAuth proxy, restricted to an allowlist of GitHub usernames.

## Tools

| Tool | Description |
|---|---|
| `list_bookmarks` | Search/list, newest first; Linkding query syntax (`#tag`, `!unread`, …) |
| `get_bookmark` | Full detail for one bookmark, including notes and archive URL |
| `check_url` | Is a URL already bookmarked? Returns scraped page metadata too |
| `add_bookmark` | Bookmark a URL — title/description/notes/tags; upserts by URL |
| `edit_bookmark` | Change url / title / description / notes / tags / unread / shared |
| `archive_bookmark` / `unarchive_bookmark` | Move to/from the archive (reversible) |
| `delete_bookmark` | Permanent delete; requires `confirm=true` |
| `list_tags` | Show all tags |
| `list_snapshots` | Archival snapshots: local HTML assets + Internet Archive URL |

Bookmarks are matched by numeric id, exact URL, or title/URL substring; ambiguous
matches return candidates so the model can retry with an id. Adding a URL that is
already bookmarked updates the existing bookmark (Linkding upserts by URL); omitted
title/description are scraped from the page.

## Setup

### 1. Linkding API token

In Linkding: **Settings → Integrations → REST API**. Copy the token into
`LINKDING_API_TOKEN` (or a secret file via `LINKDING_API_TOKEN_FILE`).

### 2. GitHub OAuth app (connector authentication)

1. <https://github.com/settings/developers> → **OAuth Apps → New OAuth App**.
2. **Authorization callback URL**: `https://linkding-mcp.example.com/auth/callback`
   (your `MCP_BASE_URL` + `/auth/callback`).
3. Register, generate a client secret, and set `GITHUB_CLIENT_ID` /
   `GITHUB_CLIENT_SECRET` / `ALLOWED_GITHUB_USERS`.

Leaving the client ID/secret unset runs the server **unauthenticated** — local
testing only.

### 3. Configuration reference

| Variable | Required | Description |
|---|---|---|
| `LINKDING_URL` | yes | Linkding base URL, e.g. `https://links.example.com` |
| `LINKDING_API_TOKEN` | yes | API token (or `LINKDING_API_TOKEN_FILE`) |
| `TZ` | no | Timezone for date display |
| `MCP_BASE_URL` | with auth | Public URL of this server |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | with auth | OAuth app credentials (or `_FILE`) |
| `ALLOWED_GITHUB_USERS` | with auth | Comma-separated GitHub logins allowed in |
| `CONSENT_MODE` | no | `external` (default), `true`, `remember`, `false` — see below |
| `ALLOWED_CLIENT_REDIRECT_URIS` | no | Redirect-URI patterns clients may register (default: claude.ai callback + localhost) |
| `HOST` / `PORT` / `MCP_PATH` | no | Bind address (`0.0.0.0`), port (`8000`), path (`/mcp`) |
| `FASTMCP_HOME` | no | OAuth client-registration storage (`/data` in Docker) |

### 4. Run it

See [`compose.example.yml`](compose.example.yml). Expose it publicly at
`MCP_BASE_URL` through your reverse proxy; optionally restrict ingress to Anthropic's
egress range (`160.79.104.0/21`). Persist `/data` or connected clients must
re-authorize after every restart.

### 5. Verify, then connect Claude

```bash
npx @modelcontextprotocol/inspector   # → https://linkding-mcp.example.com/mcp
```

Then claude.ai (or Claude Desktop) → **Settings → Connectors → Add custom connector**
with the same URL. You'll land on GitHub's authorize page; approve, and the tools
appear. Ask Claude: *"what did I bookmark about docker?"*

### Why `CONSENT_MODE=external` is the default

FastMCP's built-in consent page (as of 3.4.4) regenerates its CSRF token on every GET
of the consent URL. Browsers and claude.ai routinely prefetch that URL, invalidating
the token the visible page holds, so submitting the form fails with **"Invalid or
expired consent token"**. `external` skips that page and delegates consent to GitHub's
own authorization screen. The client redirect-URI allowlist (claude.ai + localhost by
default) prevents the classic risk of a consent-less flow — an arbitrary
dynamically-registered client silently capturing an authorization code.

## Failure modes

- **401 from Linkding** → the API token is wrong or was revoked; copy it again from
  Settings → Integrations → REST API.
- **GitHub login succeeds but tools are denied** → your login isn't in
  `ALLOWED_GITHUB_USERS` (check logs for `denied authenticated GitHub user`).
- **Connector breaks after a redeploy** → `/data` wasn't persisted, or the GitHub
  client secret changed (registration storage is keyed to it). Re-add the connector.
- **`list_snapshots` shows no local snapshots** → Linkding's HTML snapshots require
  `LD_ENABLE_SNAPSHOTS=True` on the Linkding instance; the Internet Archive URL only
  appears when Linkding's web-archive integration is enabled.

## Development

```bash
uv sync
uv run pytest
```

## License

MIT