Linkwarden MCP Server

linkwarden mcp服务器

一种模型上下文协议（MCP）服务器，为AI助手提供对Linkwarden实例的编程访问。Linkwarden是一个自托管的书签管理服务，此MCP服务器使AI代理能够与Linkwarden的书签集合、链接和搜索功能进行交互。

特性

• 收集管理：使用API完全支持创建、读取和删除集合
• 链路管理：创建、读取、存档和删除具有全面功能的链接
• 标签管理：按ID获取所有标签并删除标签
• 高级搜索：使用强大的过滤和分页功能搜索链接
• 公共收藏访问：访问公共收藏及其元数据
• 工具集选择性：仅启用所需的工具
• 只读模式：生产环境的可选安全模式
• 灵活的配置：支持命令行标志、环境变量和配置文件

演示

克劳德代码

可用工具

tools-in-claude-code

使用示例很少

保存链接：

save-link-in-claude-code

搜索链接： search-link-in-claude-code

安装

先决条件

• 访问Linkwarden实例（自托管或云）
• 具有适当权限的Linkwarden API令牌

A.使用Docker（推荐）

使用linkwarden mcp服务器最简单的方法是通过Docker。预构建的镜像可以在GitHub容器注册表上找到。

拉取最新图像

docker pull ghcr.io/irfansofyana/linkwarden-mcp-server:latest

拉取特定版本

# Pull a specific version (e.g., v1.0.0)
docker pull ghcr.io/irfansofyana/linkwarden-mcp-server:1.0.0

# Or with 'v' prefix
docker pull ghcr.io/irfansofyana/linkwarden-mcp-server:v1.0.0

可用标签：

• latest -主分支最新稳定版本
• v{major}.{minor}.{patch} -特定版本（例如。， v1.0.0)
• {major}.{minor}.{patch} -不带“v”前缀的特定版本（例如。， 1.0.0)
• {major}.{minor} -次要版本的最新补丁（例如。， 1.0)
• {major} -主要版本的最新次要版本和补丁（例如。， 1)

B.从源头构建

如果您更喜欢从源代码构建：

git clone https://github.com/irfansofyana/linkwarden-mcp-server.git
cd linkwarden-mcp-server
make build

建造的先决条件：

• 转到1.23或更高版本
• 制造

C.使用Go Install

go install github.com/irfansofyana/linkwarden-mcp-server/cmd/linkwarden-mcp-server@latest

配置

服务器可以使用命令行标志、环境变量或配置文件进行配置。

所需配置

• --base-url：您的Linkwarden实例URL（或 LINKWARDEN_BASE_URL 环境变量）
• --token：您的Linkwarden API代币（或 LINKWARDEN_TOKEN 环境变量）

可选配置

• --toolsets：以逗号分隔的要启用的工具集列表（默认值：全部）
• --read-only：启用只读模式（禁用写入操作）
• --log-file：日志文件的路径

例子

命令行标志

./linkwarden-mcp-server \
  --base-url https://your-linkwarden-instance.com \
  --token your-api-token-here \
  --toolsets search,collection,link,tags

环境变量

export LINKWARDEN_BASE_URL=https://your-linkwarden-instance.com
export LINKWARDEN_TOKEN=your-api-token-here
export TOOLSETS=search,collection,link,tags
./linkwarden-mcp-server

可用工具集

收集工具集

读取操作：

• get_all_collections：检索所有收藏
• get_collection_by_id：获取具体的收藏详细信息
• get_public_collections_links：从公共收藏中获取链接
• get_public_collections_tags：从公共收藏中获取标签
• get_public_collection_by_id：按ID获取公共收藏

写入操作：

• create_collection：创建新收藏
• delete_collection_by_id：删除现有收藏

链接工具集

读取操作：

• get_all_links：通过过滤和分页检索所有链接
• get_link_by_id：获取具体链接详细信息

写入操作：

• create_link：使用元数据和标签创建新链接
• delete_link_by_id：删除现有链接
• delete_links：按ID删除多个链接
• archive_link：按ID存档链接

标签工具集

读取操作：

• get_all_tags：检索所有标签

写入操作：

• delete_tag_by_id：按ID删除标签

搜索工具集

• search_links：使用各种过滤器搜索链接，包括：

- 搜索查询字符串 - 排序和分页 - 集合ID筛选 - 标签ID过滤

特性

搜索功能

• 跨链接全文搜索
• 按名称、URL、描述、文本内容和标签搜索
• 按集合ID和标签ID筛选
• 排序结果和分页支持
• 在公共收藏中搜索

链路管理

• 列出所有具有全面过滤选项的链接
• 按ID获取链接详细信息
• 创建具有丰富元数据（名称、URL、描述、标签、集合）的新链接
• 删除单个或多个链接
• 存档链接以供保存
• 支持使用集合和标签进行链接组织

标签管理

• 列出Linkwarden实例中的所有标签
• 按ID删除标签
• 链接和集合中的基于标签的过滤

收集管理

• 列出所有收藏
• 按ID获取收藏详细信息
• 使用元数据（名称、描述、颜色、图标）创建新集合
• 按ID删除集合
• 支持嵌套集合（父子关系）

公共收藏访问

• 无需身份验证即可访问公共集合
• 从公共收藏中检索链接
• 从公共收藏中获取标签
• 在公共收藏中搜索
• 公共内容的高级过滤选项

使用示例

启用所有工具

./linkwarden-mcp-server \
  --base-url https://your-linkwarden-instance.com \
  --token your-api-token-here

只读模式

./linkwarden-mcp-server \
  --base-url https://your-linkwarden-instance.com \
  --token your-api-token-here \
  --read-only

启用特定工具集

./linkwarden-mcp-server \
  --base-url https://your-linkwarden-instance.com \
  --token your-api-token-here \
  --toolsets search,link

与MCP客户端一起使用

linkwarden mcp服务器使用stdio传输，可以与任何兼容mcp的客户端集成。

在Claude Desktop中使用Docker

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "linkwarden": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e", "LINKWARDEN_BASE_URL=https://your-linkwarden-instance.com",
        "-e", "LINKWARDEN_TOKEN=your-api-token-here",
        "ghcr.io/irfansofyana/linkwarden-mcp-server:latest"
      ]
    }
  }
}

具有可选配置：

{
  "mcpServers": {
    "linkwarden": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e", "LINKWARDEN_BASE_URL=https://your-linkwarden-instance.com",
        "-e", "LINKWARDEN_TOKEN=your-api-token-here",
        "-e", "TOOLSETS=search,collection,link",
        "-e", "READ_ONLY=true",
        "ghcr.io/irfansofyana/linkwarden-mcp-server:latest"
      ]
    }
  }
}

使用Docker和Claude代码

在Claude Code中添加到MCP设置中：

{
  "mcpServers": {
    "linkwarden": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e", "LINKWARDEN_BASE_URL=https://your-linkwarden-instance.com",
        "-e", "LINKWARDEN_TOKEN=your-api-token-here",
        "ghcr.io/irfansofyana/linkwarden-mcp-server:latest"
      ]
    }
  }
}

将Docker与其他MCP客户端一起使用

对于任何支持stdio传输的MCP客户端：

docker run --rm -i \
  -e LINKWARDEN_BASE_URL="https://your-linkwarden-instance.com" \
  -e LINKWARDEN_TOKEN="your-api-token-here" \
  ghcr.io/irfansofyana/linkwarden-mcp-server:latest

Docker运行选项说明：

• --rm -容器退出时自动移除
• -i -保持STDIN打开以进行stdio通信
• --init -使用init进程正确处理信号
• -e -设置配置的环境变量

测试Docker镜像

要验证Docker镜像是否正常工作：

# Test with --version (not yet implemented, will connect to stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0","clientInfo":{"name":"test","version":"1.0"}}}' | \
docker run --rm -i \
  -e LINKWARDEN_BASE_URL="https://your-linkwarden-instance.com" \
  -e LINKWARDEN_TOKEN="your-api-token-here" \
  ghcr.io/irfansofyana/linkwarden-mcp-server:latest

基于二进制的集成

如果你从源代码构建或通过Go安装，你也可以直接使用二进制文件。

克劳德桌面（二进制）

添加到您的 claude_desktop_config.json:

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

其他MCP客户端（二进制）

服务器使用stdio传输，因此可以与支持stdio通信的任何MCP客户端集成。

发展

先决条件

• 转到1.23或更高版本
• 制造
• Docker（用于某些开发任务）

设置

git clone https://github.com/irfansofyana/linkwarden-mcp-server.git
cd linkwarden-mcp-server
make deps

建筑

make build          # Build the binary
make clean          # Clean build artifacts
make install        # Install to GOPATH

测试

make test           # Run all tests
make test-unit      # Run unit tests only
make test-integration # Run integration tests

代码质量

make lint           # Run linter
make fmt            # Format code

SDK生成

Linkwarden客户端SDK是根据OpenAPI规范自动生成的：

make generate-sdk   # Generate SDK from OpenAPI spec

建筑

核心组件

• 服务器：使用stdio传输的MCP服务器实现
• 工具集：用于组织功能的模块化系统
• 验证：全面的参数验证和错误处理
• 客户端：自动生成的Linkwarden API客户端

工具集系统

服务器使用模块化工具集系统，该系统允许：

• 选择性启用功能
• 安全只读模式
• 有组织的工具分组
• 使用新工具集轻松扩展

运输

目前支持与MCP客户端通信的stdio传输。

技术实现

此MCP服务器使用代码生成方法构建，该方法利用OpenAPI规范创建类型安全的API客户端和MCP工具。

运作原理

1. OpenAPI规范：服务器使用OpenAPI规范作为Linkwarden的API，最初基于官方 林肯监狱长文件 经过修改以提高可用性和类型安全性。

1. SDK生成：Go客户端SDK是使用OpenAPI规范自动生成的 oapi-codegen，提供：

- 类型安全的HTTP客户端 - 请求/响应结构 - 身份验证处理 - 全面的错误处理

1. MCP工具生成：每个API端点都包装为一个MCP工具，其中包含：

- 参数验证和类型转换 - 结构化错误处理 - 一致的响应格式 - 读/写操作分离

开发工作流程

# Update OpenAPI specification
# Edit api/linkwarden.openapi.yaml

# Generate SDK
make generate-sdk

# Build and test
make build
make test

这种方法确保MCP服务器与Linkwarden API保持同步，并为人工智能助手提供强大的类型安全接口。

致谢

该项目的灵感来自并建立在 razorpay mcp服务器 该库提供了在Go中实现MCP服务器的综合示例。模块化架构、工具集系统和许多实现模式都是从他们的工作中改编而来的。

贡献

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过
6. 提交拉取请求

许可证

该项目是开源的，可在 MIT许可证.

支持

对于问题和疑问：

• GitHub问题： 报告错误或请求功能
• 文档： 项目文件

更新日志

最新变化

• 添加了全面的链接管理工具集
• 实现了链接创建、删除和归档功能
• 通过完整的CRUD操作增强收集管理
• 实施公共收藏访问工具
• 通过高级过滤增强搜索功能
• 增加了安全生产只读模式
• 改进了参数验证和错误处理