# 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)](https://modelcontextprotocol.io/) server for [linkding](https://linkding.link/), 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

## Installation

### Via uvx (recommended)

```bash
uvx linkding-mcp
```

### Via pip

```bash
pip install linkding-mcp
```

### Development installation

```bash
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):**

```json
{
  "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):**

```json
{
  "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

```json
{
  "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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

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

### Running tests

```bash
pytest
```

### Code formatting

```bash
black src tests
isort src tests
ruff check src tests
```

## License

MIT License - see [LICENSE](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](https://github.com/sissbruecker/linkding/blob/master/docs/API.md).