Linkwarden MCP

An MCP server that exposes a Linkwarden bookmark collection as a tool set, running as a stateful agent on Cloudflare Workers. Point an MCP client (Claude, etc.) at the deployed endpoint and it can browse, search, filter, create, and archive links directly against your own Linkwarden instance.

How it works

Every tool call goes straight to the Linkwarden REST API on your live instance — there's no index, cache, or background sync involved.

MCP client ──HTTP/SSE──► Worker (/mcp) ──► LinkwardenMCP (Durable Object)
                                                  │
                                    LINKWARDEN_URL + LINKWARDEN_TOKEN → Linkwarden API

LinkwardenMCP is a McpAgent hosted on a Durable Object.

Related MCP server: OpenViking MCP Server

Tools

Setup

npm install
wrangler secret put LINKWARDEN_URL     # base URL of your Linkwarden instance

LINKWARDEN_TOKEN (a Linkwarden API access token) is read from Cloudflare's Secrets Store, not a plain Wrangler secret. Create it once per account and it's reusable across Workers:

wrangler secrets-store secret create <store-id> \
  --name linkwarden-token --scopes workers --remote

wrangler.jsonc then binds it via secrets_store_secrets:

"secrets_store_secrets": [
  { "binding": "LINKWARDEN_TOKEN", "store_id": "<store-id>", "secret_name": "linkwarden-token" }
]

For local dev, create a local-only secret with the same name (omit --remote) so wrangler dev has something to read.

See CLAUDE.md for the full architecture and binding reference.

Development

npm run dev         # wrangler dev — local development with hot reload
npm run test        # vitest run
npm run typecheck   # tsc --noEmit

Deploy

Cloudflare Workers Builds is connected to this repo — pushing to master deploys automatically (npm run build then wrangler deploy). npm run deploy remains available for manual/ad-hoc deploys. Either way, the linkwarden-token secret must exist in the account's Secrets Store — it is never stored in the repo.

Stack

• Cloudflare Workers + Durable Objects (SQLite-backed)

• Cloudflare Agents SDK (agents/mcp)

• MCP TypeScript SDK

• TypeScript, Zod for tool input schemas, Vitest