linkding-mcp

⚠️ Warning: This is an experimental, unofficial MCP server in very early development stage. The code is "vibe coded", minimally tested and may be unstable. Not recommended for production environments.

A Model Context Protocol (MCP) server for linkding, a self-hosted bookmark manager. This is not an official Linkding package.

Features

• 🔍 Bookmark Management: Create, update, delete and search bookmarks

• 🏷️ Tag Management: Create, list and add tags to bookmarks

• 📦 Archiving: Archive and unarchive bookmarks

• 🔎 Advanced Search: Full-text search in bookmarks with various filters

• 📊 Statistics: Overview of bookmark statistics

• 📂 Bundle Management: Create and manage bookmark collections

• 📎 Asset Management: Manage file assets (uploads and snapshots)

• 👤 User Profiles: Access user profile and settings

• 🕒 Advanced Filters: Filter by modification and creation date

• 🔧 Configurable: Optional automatic scraping can be disabled

Related MCP server: paperless-mcp

Installation

Via uvx (recommended)

uvx linkding-mcp

Via pip

pip install linkding-mcp

Development installation

git clone https://github.com/jensneuhaus/linkding-mcp.git
cd linkding-mcp
pip install -e .

Configuration

Environment Variables

The server requires these environment variables:

• LINKDING_URL: The URL to your linkding instance (e.g. https://bookmarks.example.com)

• LINKDING_API_KEY: Your linkding API key (found under /settings/integrations)

MCP Client Configuration

Add the server to your MCP client configuration:

Claude Desktop (cline.json)

Direct from GitHub Repository (recommended):

{
  "mcpServers": {
    "linkding": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/jensneuhaus/linkding-mcp.git",
        "linkding-mcp"
      ],
      "env": {
        "LINKDING_URL": "https://...",
        "LINKDING_API_KEY": "..."
      }
    }
  }
}

Via PyPI (if available):

{
  "mcpServers": {
    "linkding": {
      "command": "uvx",
      "args": ["linkding-mcp"],
      "env": {
        "LINKDING_URL": "https://your-linkding.example.com",
        "LINKDING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using with direct Python

{
  "mcpServers": {
    "linkding": {
      "command": "python",
      "args": ["-m", "linkding_mcp.server"],
      "env": {
        "LINKDING_URL": "https://your-linkding.example.com", 
        "LINKDING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

📚 Reading List

• get_reading_list - Get all bookmarks with #readlater tag

• add_to_reading_list - Add bookmark directly to reading list

Bookmark Management

• create_bookmark - Create new bookmark (with optional disable_scraping)

• get_bookmarks - List bookmarks (with search, filter and date options)

• get_bookmark - Get single bookmark by ID

• update_bookmark - Update bookmark details

• delete_bookmark - Delete bookmark

• check_bookmark - Check if URL already exists as bookmark

Archiving

• archive_bookmark - Archive bookmark

• unarchive_bookmark - Remove bookmark from archive

Tag Management

• get_tags - List all available tags

• create_tag - Create new tag

• add_tag_to_bookmark - Add tag to existing bookmark

Bundle Management

• get_bundles - List all bundles

• get_bundle - Get single bundle by ID

• create_bundle - Create new bundle

• update_bundle - Update bundle

• delete_bundle - Delete bundle

Asset Management

• get_bookmark_assets - List assets of a bookmark

• get_bookmark_asset - Get single asset

• delete_bookmark_asset - Delete asset

Advanced Features

• search_bookmarks - Advanced full-text search with filters

• get_bookmark_stats - Statistics about your bookmark collection

• get_user_profile - Get user profile and settings

Examples

Creating a new bookmark

# Via MCP client - simple
create_bookmark(
    url="https://example.com",
    title="Example Website",
    description="An example website",
    tag_names=["example", "test"]
)

# With disabled scraping
create_bookmark(
    url="https://example.com",
    title="Manual Title",
    description="Manual Description",
    disable_scraping=True
)

Search and filter bookmarks

# All unread bookmarks
search_bookmarks(unread=True)

# Search by text
search_bookmarks(q="python tutorial")

# Filter by tags
get_bookmarks(q="tag:programming")

# Filter by date
get_bookmarks(added_since="2026-01-01T00:00:00Z")

# Filter by bundle
get_bookmarks(bundle=1)

Bundle management

# Create new bundle
create_bundle(
    name="Python Resources",
    search="python tutorial",
    any_tags="python programming",
    excluded_tags="outdated"
)

# List bundles
get_bundles()

# Update bundle
update_bundle(
    bundle_id=1,
    name="Updated Python Resources",
    order=5
)

Asset management

# Show assets of a bookmark
get_bookmark_assets(bookmark_id=123)

# Get asset details
get_bookmark_asset(bookmark_id=123, asset_id=456)

# Delete asset
delete_bookmark_asset(bookmark_id=123, asset_id=456)

Development

Setup

git clone https://github.com/jensneuhaus/linkding-mcp.git
cd linkding-mcp
pip install -e ".[dev]"

Running tests

pytest

Code formatting

black src tests
isort src tests
ruff check src tests

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

API Reference

For more details about the linkding REST API, see the official documentation.