linkwarden-mcp

一个为 Linkwarden 提供的 模型上下文协议 服务器。Linkwarden 是一个自托管的书签管理器，会为每个保存的页面保留永久副本。

它允许 MCP 客户端（Claude Code、Claude Desktop、Codex）搜索书签集合，将其组织到集合和标签中，并读取已保存页面的存档文章文本，从而无需再次访问实时网站即可对已存档的链接进行摘要或引用。

📖 完整文档请访问 linkwarden-mcp.ni-c.de

注意： Linkwarden 发布的 API 参考文档不完整。此服务器是根据 linkwarden/linkwarden 中 apps/web/pages/api/v1/** 的路由和 packages/lib/schemaValidation.ts 的请求模式编写的，并于 2026-08-17 针对 v2.16.0 进行了验证。这两个文件是此处所有工具的权威来源。

要求

• Node.js ≥ 22

• 一个正在运行的 Linkwarden 实例

• 一个访问令牌，在 设置 → 访问令牌 下创建

Linkwarden 没有按令牌划分的作用域：一个令牌拥有创建它的账户的全部权限。请创建一个专用账户，仅授予此服务器应看到的集合的访问权限，而不是提供管理员令牌。

Related MCP server: linkwarden-mcp

配置

请使用 https://。 通过纯 HTTP 传输时，令牌会以未加密方式传输；除非主机是本地主机，否则服务器会打印警告。对于自签名证书，建议使用适当的内部 CA，而不是 LINKWARDEN_INSECURE_TLS。

令牌在被读取后会从进程环境中移除，因此子进程或 /proc/<pid>/environ 中不可见。

即使没有凭据，服务器仍会启动并列出其工具，因此注册表和检查器可以对其进行内省；此时每个调用都会失败并显示设置说明，而不会访问 API。

安装

Claude Code

claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp

Claude Desktop

{
  "mcpServers": {
    "linkwarden": {
      "command": "npx",
      "args": ["-y", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_URL": "https://links.example.net",
        "LINKWARDEN_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.linkwarden]
command = "npx"
args = ["-y", "linkwarden-mcp"]
env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }

从源码安装

npm install && npm run build
LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js

Docker

docker build -t linkwarden-mcp .
docker run --rm -i \
  -e LINKWARDEN_URL=https://links.example.net \
  -e LINKWARDEN_TOKEN=… \
  linkwarden-mcp

工具

读取

写入

当 LINKWARDEN_READ_ONLY=true 时完全不注册。标记为 🔒 的工具需要确认令牌。

故意不暴露的功能

• 访问令牌管理（/tokens）。能够创建 API 凭据的工具是权限提升的攻击面，书签服务器不应持有此类功能。

• 用户管理（/users、账户删除）。超出范围。

• 备份导出和导入（/migration）。导出会将整个实例转储到模型上下文中；导入可能破坏实例。

• 高亮标记。 创建高亮需要精确的字符偏移量指向存档文档，模型无法有意义地生成这些偏移量，且 Linkwarden 没有提供列出现有高亮的路由。

• 存档上传和签名的 preserved URL，这需要配置 NEXT_PUBLIC_USER_CONTENT_DOMAIN。

• 已弃用的 GET /links 列表路由 — search_links 改用 GET /search，这也是 Linkwarden 自身推荐的方式。

安全性

• 破坏性工具是两步操作。 第一次调用返回一个绑定到确切目标的短期确认令牌；只有携带该令牌的第二次调用才会执行操作。模型无法自行满足此门控条件，且为一个链接、标签集或更改颁发的令牌不能重放用于另一个。

• 扩大可见性被视为破坏性操作。 发布集合和更改链接的 URL（这会删除旧页面的所有存档副本）都需要确认，而不仅仅是删除操作。

• 确认提示从不引用 Linkwarden 中的内容。 标题、URL、描述和集合名称来自已保存页面和实例的其他用户；模型读取的文本中仅出现计数和 ID。

• 返回的内容被标记为不可信数据，特别是存档文章文本，它由控制目标网站的任何人所写。

• 部分更新不会清除字段。 Linkwarden 的更新路由会替换整个记录，因此此服务器会读取当前状态并进行合并 — 否则更新会静默地剥离链接的标签或集合的协作者。

• 200 状态码本身不可信。 几个 Linkwarden 路由会以 HTTP 200 和正文中的错误句子报告失败，而一个没有处理所使用方法的路由会返回 200 且没有任何内容。这两种情况都会报告为错误，而不是成功的写入。

• 错误正文会被截断，HTML 错误页面会被完全丢弃，重定向永远不会被跟随（因此 bearer 令牌不能重放到其他主机），并且每个请求都带有超时。

• LINKWARDEN_READ_ONLY=true 不会注册写入工具。

• 剩余风险： 在您配置的令牌权限范围内，被要求执行破坏性操作且用户确认的模型仍然可以执行。请限定账户范围，并保持主机级别的权限提示。

开发

npm install
npm run build
npm test
npm run test:coverage
npm run lint
npm run format
npm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md 是生成的；如果提交的副本与代码不再匹配，CI 会失败。文档站点位于 docs/ 中，带有其自己的 package.json 和锁文件 — VitePress 不得出现在根安装中，根安装会在 Docker 构建和整个测试矩阵中运行。

请参阅 CONTRIBUTING.md。

发布

一切由标签驱动；没有手动发布步骤。

1. 将 CHANGELOG.md 中的 [Unreleased] 部分移至新版本并为其添加日期。发布工作流使用 awk 提取该部分，因此 ## [x.y.z] 标题格式很重要。

2. 更新 package.json 中的 version 字段。

3. npm run lint && npm run build && npm run test:coverage。

4. 提交，然后创建一个签名注释标签：

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1

随后 release.yml 会验证标签是否与 package.json 匹配，通过受信任发布（OIDC——不存在可泄露的 npm 令牌）并附带 provenance 发布到 npm，将版本同步到 server.json 的两个包条目中，发布到 MCP 注册表，并从 changelog 部分创建 GitHub 发布。ci.yml 会并行将多架构容器镜像推送到 GHCR。

如果注册表步骤失败，请在 main 分支上修复它，然后手动运行 mcp-registry.yml 工作流。重新运行失败的作业不是选项：它会检出不可变的标签，因此 main 上的修复永远无法到达它。

License

MIT © Willi Thiel