Linkwarden MCP Server

A highly-optimized Model Context Protocol (MCP) server that provides AI assistants (such as OpenCode, Claude Code, Cursor, and Windsurf) with programmatic access to your Linkwarden instances.

Linkwarden is a self-hosted, collaborative bookmark management service. This MCP server enables AI agents to seamlessly interact with your collections, search bookmarks, manage tags, and subscribe to RSS feeds!

---

Key Features

• Collection Management: Create, read, and delete collections with nested parent-child structure support.
• Link Preservation: Save links, update metadata, archive webpages for preservation, and bulk delete bookmarks.
• RSS Capabilities: Subscribe to RSS feeds, list active subscriptions, and auto-save new posts directly to designated collections.
• Tag Management: List all active tags, organize bookmarks, and delete tags by ID.
• Highlights Support: Retrieve, create, or delete text highlights and annotations on bookmarks.
• Deep Search: Deep search (by text content, name, URL, tag) with paging.
• Production Safety: Optional Read-Only Mode to prevent AI agents from making destructive modifications.
• Selective Toolsets: Enable only the specific tools you need (rss, search, collection, link, tags, highlights).

---

Available Toolsets & Tools

The server organizes operations into selective modular toolsets. Here is the complete reference of all available tools:

Toolset	Tool Name	Description	Operation
rss	list_rss_subscriptions	Retrieve all active RSS feed subscriptions	Read
	create_rss_subscription	Subscribe to a new RSS feed and designate a collection	Write
	delete_rss_subscription	Unsubscribe/Delete an RSS subscription by ID	Write
collection	get_all_collections	Retrieve all nested and top-level collections	Read
	get_collection_by_id	Get details and metadata of a specific collection	Read
	create_collection	Create a new collection with customizable icon and color	Write
	delete_collection_by_id	Delete a collection by its ID	Write
	get_public_collection_by_id	Access a public collection by ID without authentication	Read
	get_public_collections_links	Get links from a public collection	Read
	get_public_collections_tags	Get tags from a public collection	Read
link	get_all_links	Retrieve all links with comprehensive filtering and pagination	Read
	get_link_by_id	Retrieve specific details of a bookmark by ID	Read
	create_link	Create a bookmark with tags, description, and collection	Write
	delete_link_by_id	Delete an individual bookmark	Write
	delete_links	Bulk delete a list of bookmarks by their IDs	Write
	archive_link	Trigger archival preservation for a bookmark	Write
tags	get_all_tags	Retrieve all tags across your instance	Read
	delete_tag_by_id	Delete a tag by its ID	Write
search	search_links	Deep search (by text content, name, URL, tag) with paging	Read
highlights	get_highlights	Retrieve all highlights associated with a link	Read
	create_highlight	Create or update a highlight on a link	Write
	delete_highlight	Delete a highlight by its highlight ID	Write

---

Installation & Setup

Option A: Using Docker (Recommended)

Run the pre-built, highly-optimized container from the container registry:

docker pull git.nokopia.com/yuris/linkwarden-mcp-server:latest

Option B: Building From Source

# Clone the repository
git clone https://git.nokopia.com/yuris/linkwarden-mcp-server.git
cd linkwarden-mcp-server

# Install Go dependencies & Generate SDK
make install-deps
make generate-sdk

# Build the binary
make build

---

Configuration

Pass configuration via command-line flags, environment variables, or a config file.

Required Configuration

• --base-url / LINKWARDEN_BASE_URL: The URL of your Linkwarden instance (e.g., https://links.yourdomain.com).
• --token / LINKWARDEN_TOKEN: Your API token (generate this in Settings -> API Keys in your Linkwarden dashboard).

Optional Configuration

• --toolsets: Comma-separated list of toolsets to enable (e.g., rss,search,link,highlights). Default is all toolsets.
• --read-only: Disables all write/destructive operations for extra safety.
• --log-file: Path to store the server's logs.

---

Integration with MCP Clients

The server communicates via standard stdio transport. Here are the integration configurations for popular clients:

1. OpenCode

Add the following to your OpenCode configuration (e.g., ~/.config/opencode/opencode.json):

Docker-based Setup (Recommended)

{
  "mcp": {
    "linkwarden": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--init",
        "-e", "LINKWARDEN_BASE_URL=https://your-linkwarden-instance.com",
        "-e", "LINKWARDEN_TOKEN=your-api-token-here",
        "git.nokopia.com/yuris/linkwarden-mcp-server:latest"
      ],
      "enabled": true
    }
  }
}

Binary-based Setup

{
  "mcp": {
    "linkwarden": {
      "type": "local",
      "command": ["/absolute/path/to/linkwarden-mcp-server", "stdio"],
      "environment": {
        "LINKWARDEN_BASE_URL": "https://your-linkwarden-instance.com",
        "LINKWARDEN_TOKEN": "your-api-token-here"
      },
      "enabled": true
    }
  }
}

2. Claude Code

Run the following command in your terminal to add the MCP server automatically:

claude mcp add /absolute/path/to/linkwarden-mcp-server stdio --base-url "https://your-linkwarden-instance.com" --token "your-api-token-here"

Or add it manually to ~/.claude.json:

{
  "mcpServers": {
    "linkwarden": {
      "command": "/absolute/path/to/linkwarden-mcp-server",
      "args": ["stdio"],
      "env": {
        "LINKWARDEN_BASE_URL": "https://your-linkwarden-instance.com",
        "LINKWARDEN_TOKEN": "your-api-token-here"
      }
    }
  }
}

3. Cursor or Windsurf

Add a new MCP server in your IDE settings:

• Type: command
• Command:

  /absolute/path/to/linkwarden-mcp-server stdio --base-url "https://your-linkwarden-instance.com" --token "your-api-token-here"
  

---

Development & Contributions

The client SDK is generated from the OpenAPI spec (api/linkwarden.openapi.yaml) using oapi-codegen.

# Regenerate SDK after OpenAPI edits
make generate-sdk

# Run standard test suite
make test

For more info, check out the Development Guide.

---

License & Support

• Licensed under the Apache License 2.0.
• Project Home: git.nokopia.com/yuris/linkwarden-mcp-server