Linkwarden

linkwarden-mcp

这是一个面向 Linkwarden 的模型上下文协议（MCP）服务。Linkwarden 是一款可自托管的书签管理器，会永久保存它收录的每个页面副本。

它允许 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端搜索书签集、将书签整理到不同集合和标签中，并读取已保存页面中保留的文章文本，这样就能对已归档的链接进行摘要或引用，而无需再次获取实时网站内容。

二十八个工具是上限，而不是最低要求：设置 LINKWARDEN_ALLOW_TOOLS=essential 即可只注册精选的八个工具。相比二十八个工具，模型从八个工具中更容易可靠地选出合适的工具——请参阅选择要加载的工具。

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

有何不同

读取 Linkwarden 保留的内容。 Linkwarden 会永久保存它收录的每个页面副本。get_link_content 会提供文章文本，因此无需再次获取实时网站内容，就能对已保存的链接进行摘要或引用——长篇文章也会分段提供，而不会一次性全部输出。

整理内容而不覆盖数据。 Linkwarden 的更新路由会替换整个记录。本服务会先读取当前状态再合并，因此更改标题不会悄悄移除链接的标签或集合的协作者。

输出采用允许列表。 Linkwarden 会返回完整的 Prisma 行；此处结果中的每个字段都经过明确指定。文章文本不会出现在列表结果中，集合成员的姓名和电子邮件地址会被移除，未来版本新增的列也不会在模型不知情的情况下进入上下文。

要求

• Node.js ≥ 22
• 正在运行的 Linkwarden 实例
• 访问令牌，可在 Settings → Access Tokens 下创建

Linkwarden 不支持为每个令牌设置权限范围：令牌拥有创建它的账户的全部权限。请创建一个仅可访问此服务应查看的集合的专用账户，而不要交给它管理员令牌。

配置

变量	必需	说明
LINKWARDEN_URL	是	基础 URL，例如 https://links.example.net（不含 /api/v1）
LINKWARDEN_TOKEN	是	从 Settings → Access Tokens 获取的访问令牌
LINKWARDEN_READ_ONLY	否	true 仅注册读取工具
LINKWARDEN_ALLOW_TOOLS	否	以逗号分隔的工具名称、list_* 前缀，或用于精选预设的 essential
LINKWARDEN_DENY_TOOLS	否	语法相同；从 LINKWARDEN_ALLOW_TOOLS 保留的工具中移除
ELICITATION	否	false 会将审批对话框替换为双调用令牌。不带前缀
LINKWARDEN_INSECURE_TLS	否	true 接受自签名证书（仅适用于此连接）

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

读取令牌后，令牌会从进程环境中移除，因此子进程和 /proc/<pid>/environ 中都无法看到它。

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

选择要加载的工具

LINKWARDEN_ALLOW_TOOLS 和 LINKWARDEN_DENY_TOOLS 接受以逗号分隔的工具名称；末尾的 * 可匹配整个工具系列。essential 是一个精选的八项预设，包含保存、查找和读取工具；工具参考中对此有标记。

LINKWARDEN_ALLOW_TOOLS=essential
LINKWARDEN_ALLOW_TOOLS=search_links,get_link_content,create_link
LINKWARDEN_DENY_TOOLS=bulk_*

如果某个条目未匹配任何工具，服务会中止启动并指出该条目，这样拼写错误就不会悄悄隐藏工具——否则没人能追查到某个工具缺失是由环境变量导致的。被筛选掉的工具不会注册，因此它既不会出现在 tools/list 中，也无法通过 tools/call 调用，与 LINKWARDEN_READ_ONLY 下的写入工具完全相同。

如果同时运行多个此类服务，mcp-hub 是另一种解决方案——其 /hub 端点会用六个元工具替换每个服务的所有工具。

安装

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

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、网页端的 Claude、Cursor、LibreChat——可通过 mcp-hub 访问 linkwarden-mcp：一个容器通过 Streamable HTTP 为多个 stdio MCP 服务提供服务，并通过单个密码进行 OAuth 2.1 登录，还为无法使用 OAuth 的客户端提供长期令牌。它的 /hub 端点通过六个元工具接入所有服务，因此一个连接器即可访问全部服务，无需在模型上下文中包含 N× 个工具架构；它还同时支持两个协议版本——本服务提出的问题会经由它传递给另一端的人。

它的 /config/mcp.json 使用 Claude Code 的格式，因此配置项就是你已有的那一项：

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

其中的 allowTools 和 denyTools 是中心针对每个服务设置的自身过滤器，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别以及容易因此犯下的错误，见客户端指南。

工具

每个工具都声明了 outputSchema，并在文本块之外通过 structuredContent 返回结果，因此客户端无需解析散文即可使用结果。之前只用一句话作答的七个工具——“已删除链接 42。”——现在也会返回相关字段，而这句话仍保留在文本块中。

十个读取工具都带有 untrusted: true 和 source: "linkwarden" 字段。书签标题、描述，尤其是保留的文章文本，都是由控制目标网站的人撰写的；本服务一直在 notes 中说明这一点，但那只是客户端可以读取、无法验证的文字，而字段则让这一点变得可验证。写入工具不带这些字段：它们报告本服务收到的 ID 和创建的数量。

超出预算的结果仍会丢弃列表项；超出大小限制的不可信封装仍会从最大字段中删减字符。如果两者都没有可删减的内容，现在会返回错误，而不是返回一个将超大文档作为字符串的封装：这种封装是有效的 JSON，却不是有效的答复，因为 SDK 会根据工具声明的架构检查结果。

读取

工具	描述
search_links	搜索或列出书签。支持 Linkwarden 的字段过滤器（tag:、collection:、before:、! 等）。
get_link	获取一个书签及其标签、所属合集和现有的保留格式。
get_link_content	获取已保存页面保留的文章文本；长文章会分段返回。
list_collections	列出所有合集及其链接数量；通过 parentId 表示嵌套关系。
get_collection	获取一个合集及其各成员的权限。
list_tags	列出标签及其链接数量和各自的存档设置。
get_tag	获取一个标签。
get_dashboard	获取最近添加的链接和置顶链接，与 Linkwarden 控制面板中的显示一致。
list_rss_subscriptions	列出此账户订阅的 RSS 源。
get_current_user	查看令牌所属账户及其存档默认设置。适合用于检查连接状态。
get_worker_stats	查看内容保留和搜索索引队列。仅限管理员账户——其他用户会收到 HTTP 403。

写作

当 LINKWARDEN_READ_ONLY=true 时，完全不会注册这些工具。标记为 👤 需询问人员 的工具会通过 MCP 征询机制进行确认——模型无法代替用户回答的对话框——如果客户端无法显示此类对话框，则会改用两次调用的 confirm_token。参见询问人员。

工具	描述
create_link	保存书签，可选择添加标签和集合（按需创建）。
update_link	修改标题、描述、标签或集合。仅当 URL 发生变化时需 👤 确认。
set_link_pinned	为此账户置顶或取消置顶链接。
delete_link 👤	删除书签及其保存的副本。
bulk_update_links 👤	为多个链接应用同一组标签和／或集合。
bulk_delete_links 👤	一次删除多个书签。
represerve_link 👤	删除现有存档，并重新保存页面。
delete_link_preservations 👤	删除多个链接的存档，同时保留书签。
create_collection	创建集合，可选择嵌套。
update_collection	重命名、调整集合层级或发布集合。仅发布时需 👤 确认。
delete_collection 👤	删除集合——其链接和子集合也会随之删除。
create_tags	创建标签或更改其存档设置（按名称执行插入或更新）。
rename_tag 👤	重命名标签——所有带有该标签的链接也会随之更新。
delete_tags 👤	删除标签；链接会保留。
merge_tags 👤	将多个标签合并为一个新标签。
create_rss_subscription	订阅 RSS/Atom 源。
delete_rss_subscription 👤	停止轮询源。

有意不提供的功能

• 访问令牌管理（/tokens）。能够创建 API 凭据的工具会带来权限提升风险，而书签服务不应持有此类工具。
• 用户管理（/users、删除账户）。不在范围内。
• 备份导出与导入（/migration）。导出会将整个实例的内容倾倒到模型上下文中；导入则可能将其摧毁。
• **高亮标记。**创建高亮标记需要在保存的文档中提供精确的字符偏移量，模型无法有意义地生成这些偏移量，而且 Linkwarden 没有提供列出现有高亮标记的路由。
• 存档上传和签名的 preserved URL；这些功能需要配置 NEXT_PUBLIC_USER_CONTENT_DOMAIN。
• 已弃用的 GET /links 列表路由——search_links 改用 GET /search，这也是 Linkwarden 自身推荐的方式。

安全

• 破坏性工具需要征求用户确认。 如果客户端支持 MCP elicitation，这些工具会弹出一个模型无法代替用户回答的真实对话框。如果不支持，首次调用会返回一个短期令牌，该令牌绑定到确切的目标；只有第二次调用携带该令牌时，操作才会执行。这只能证明调用使用相同参数进行了两次，不代表其他任何内容，提示文本也会说明这一点。针对某个链接、标签集或更改签发的批准，不能用于其他对象。 ELICITATION=false 会有意采用这种回退方式，绝不会移除保护措施。
• 丢失内容不只是删除。 发布收藏集、更改链接的 URL（这会删除旧页面所有已保存的副本），以及重命名标签（这会影响所有带有该标签的链接），都会要求确认。
• 确认提示绝不会引用 Linkwarden 中的内容。 标题、URL、描述和收藏集名称来自已保存的页面以及该实例的其他用户；模型能读取的文本中只会显示数量和 ID。
• Linkwarden 获取已收藏的 URL 前会先对其进行检查。 create_link、update_link 和 create_rss_subscription 会将 URL 交给一个在无头浏览器中打开它的服务端，而 get_link_content 会读取返回结果，这意味着未经检查的 URL 可以用来读取 Linkwarden 网络内部的内容。环回地址和链路本地地址（包括云元数据端点及其主机名）会被拒绝；地址会进行数值比较，因此像 [::ffff:169.254.169.254] 这样的 IPv4 映射字面量也会被拦截，主机名则会先解析再接受。私有 LAN 地址仍然允许使用——对于可自托管的书签管理器来说，将路由器的接口或内网页面加入书签是很常见的操作；这也意味着 Linkwarden 旁边的容器可以被访问。SECURITY.md 说明了这项检查的覆盖范围和不覆盖的内容，包括 RSS 源中的条目。
• 返回的内容会标记为不可信数据，尤其是由目标网站控制者撰写的已保存文章文本。
• 部分更新绝不会清空字段。 Linkwarden 的更新路由会替换整个记录，因此此服务会读取当前状态并进行合并；否则，更新可能会悄无声息地移除链接的标签或收藏集的协作者。
• 不能仅凭 HTTP 200 就信任请求成功。 Linkwarden 的多个路由会在 HTTP 200 响应正文中用错误句子报告失败；而没有处理相应请求方法的路由则会返回空内容的 200 响应。这两种情况都会报告为错误，而不会被视为写入成功。
• 错误正文会被截断，HTML 错误页面会被完全丢弃，不会跟随重定向（因此 bearer 令牌无法被重放到其他主机），并且每个请求都会设置超时。
• LINKWARDEN_READ_ONLY=true 时，根本不会注册写入工具。
• 剩余风险： 在你配置的令牌权限范围内，如果模型被要求执行破坏性操作且用户确认了该操作，它仍然可以执行。请限制账户权限，并保持主机级权限提示开启。

文档

完整指南、工具参考和安全说明见 linkwarden-mcp.ni-c.de（源文件位于 docs/）。

开发

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 中的版本一致，通过 Trusted Publishing（OIDC — 不存在可泄露的 npm 令牌）发布到 npm 并附带来源证明，将版本同步到 server.json 中的两个 package 条目，发布到 MCP registry，并根据变更日志部分创建 GitHub release。ci.yml 会并行将多架构容器映像推送到 GHCR。

如果 registry 步骤失败，请在 main 上修复，然后手动运行 mcp-registry.yml 工作流。 不能重新运行失败的作业：它会检出不可变标签，因此在 main 上的修复永远无法生效。

参与贡献

欢迎提交问题、参与讨论和发起拉取请求 — 请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道， 不要公开提交问题；相关政策见 SECURITY.md。

许可证

MIT © Willi Thiel