Linkwarden MCP

linkwarden-mcp

适用于可自托管 Linkwarden 的 MCP 服务：向 AI 咨询书签、集合和标签。

什么是 Linkwarden？

Linkwarden 是一款可自托管的开源书签管理器。你可以在一个地方收集、整理、注释和保存网页，并创建完整页面存档，以便即使原始页面消失，内容仍可阅读。它还支持协作和公开分享。

本项目将 Linkwarden HTTP API 接入 Model Context Protocol，让 Cursor、Claude、VS Code Copilot 及其他 MCP 宿主能够通过自然语言查询你的实时资料库。

Linkwarden 实用链接：

• 文档
• GitHub
• 云服务
• 演示
• 自托管设置

此服务的功能

默认情况下为只读。你可以使用：

• 18 个读取工具 - 发现（list_resources）、六项核心读取功能（搜索、获取、读取保存内容、集合、标签、概览），以及 11 个分类整理／维护工作流
• 任务工具（可选启用） - 根据意图执行写入操作，例如 save_link、smart_save_link、organise_links、create_collection、apply_triage_plan（设置匹配的写入范围后注册）
• 删除工具（可选启用） - delete_links、delete_tags、merge_tags、delete_collection（仅在删除范围内注册；写入权限不会默认包含删除权限）
• 严格拒绝列表 - 即使启用了写入功能，令牌、会话、身份验证、用户管理（GET /api/v1/users/me 除外）、迁移和整个实例的保存操作仍会被禁止

传输方式为 stdio。不运行 HTTP 服务。使用 uv / uvx 时，无需全局安装。

品牌标识／图标

共有四个展示位置（标识变更时请保持同步）：

1. stdio 宿主（Cursor、通过 mcp.json 配置的 Claude Desktop）： server_icons() 提供的 serverInfo.icons — 内嵌数据 URI，来源于 src/linkwarden_mcp/assets/icon.png，另有 HTTPS 后备图标 docs/icon-512.png（https://raw.githubusercontent.com/flumpiey/linkwarden-mcp/main/docs/icon-512.png）。website_url 为 https://linkwarden.app/。
2. Cursor 插件： .cursor-plugin/plugin.json 中的 logo → docs/linkwarden-icon.svg。
3. Claude Desktop 扩展： mcpb/icon.png（使用 npx @anthropic-ai/mcpb pack mcpb 打包）。
4. Claude.ai 远程连接器： Claude.ai 会忽略 serverInfo.icons，并使用连接器 URL 所属根域名的 favicon。如果之后托管远程 MCP，请在可注册域名根目录提供 docs/favicon.ico（例如，https://mcp.acme.com/... 对应 https://acme.com/favicon.ico）。

server.json 中的注册表元数据也将 icons[0].src 指向同一个原始 docs/icon-512.png URL。

要求

• Python ≥ 3.10（由 uvx 自动安装）
• uv（提供 uvx）
• 可访问的 Linkwarden 实例：LINKWARDEN_API_URL + LINKWARDEN_API_KEY

访问令牌

1. 登录你的 Linkwarden 实例（可自托管或使用 Cloud）。
2. 打开 设置 → 访问令牌（或前往 /settings/access-tokens）。
3. 创建一个新访问令牌，为其命名，并将令牌值复制到 LINKWARDEN_API_KEY。
4. 将 LINKWARDEN_API_URL 设为你的实例基础 URL（通常不包含 /api/v1；仅当你的部署需要时才添加 /api/v1），例如 https://links.example.com 或本地 Docker 地址 http://127.0.0.1:3000。

linkwarden-mcp 会将令牌作为 Authorization: Bearer … 发送。API 概览：API 介绍。

本地运行时，将 .env.example 复制为 .env——切勿提交 .env。凭据优先使用 Cursor 插件的配置界面，或在生产环境中使用密钥管理器。

快速开始

使用 uvx 运行 PyPI 包：

uvx linkwarden-mcp

粘贴下方的客户端配置，设置 LINKWARDEN_API_URL / LINKWARDEN_API_KEY，重启主机，然后提问：“查找我未读的 Python 书签” 或 “我的 Dev 集合里有什么？”

从 git 克隆版本（开发）：uvx --from git+https://github.com/flumpiey/linkwarden-mcp linkwarden-mcp 或 uv run --directory /path/to/linkwarden-mcp linkwarden-mcp。

安装

下方的配置会从 PyPI 获取 linkwarden-mcp。如需只读模式，请将写入范围环境变量留空。

{
  "mcpServers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/linkwarden-mcp", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

"LINKWARDEN_MCP_WRITE_SCOPES": "links,collections",
"LINKWARDEN_MCP_DELETE_SCOPES": "links"

从克隆仓库构建自己的捆绑包：

npx @anthropic-ai/mcpb pack mcpb

在 Windows 上，双击通常不会有任何反应；将文件拖入聊天则会把它作为附件添加到对话中，而不是安装。请在 Settings 中使用 Install Extension…。

**手动配置 claude_desktop_config.json 的备用方法：**编辑 Claude Desktop 配置，然后重启应用。

{
  "mcpServers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

本地克隆：

{
  "mcpServers": {
    "linkwarden": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/linkwarden-mcp", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

claude mcp add linkwarden --env LINKWARDEN_API_URL=https://links.example.com --env LINKWARDEN_API_KEY=your-token -- uvx linkwarden-mcp

{
  "mcpServers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "servers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "servers": {
    "linkwarden": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/linkwarden-mcp", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "context_servers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "linkwarden": {
      "command": "uvx",
      "args": ["linkwarden-mcp"],
      "env": {
        "LINKWARDEN_API_URL": "https://links.example.com",
        "LINKWARDEN_API_KEY": "your-token"
      }
    }
  }
}

mcpServers:
  - name: linkwarden
    command: uvx
    args:
      - linkwarden-mcp
    env:
      LINKWARDEN_API_URL: https://links.example.com
      LINKWARDEN_API_KEY: your-token

uvx linkwarden-mcp

环境变量

有效范围：links、collections、tags、raw。不支持通配符（*、all）。raw 会将有效范围扩展为所有域范围（紧急解锁选项）。

推荐配置（涵盖大多数书签工作流，无需启用所有会修改数据的工具）：

"LINKWARDEN_MCP_WRITE_SCOPES": "links,collections",
"LINKWARDEN_MCP_DELETE_SCOPES": "links"

不设置范围时的默认值：18 个工具。在 WRITE 和 DELETE 中启用全部三个域范围时：31 个工具。

如果设置了旧版 LINKWARDEN_MCP_ALLOW_WRITES / ALLOW_WRITES / LINKWARDEN_MCP_WRITES，程序会直接报错。请改用范围限定变量。

MCP 主机环境变量（.cursor/mcp.json 或 Cursor 插件 Configure）必须与进程环境变量 / .env 一致，否则范围行为会不一致。

请参阅 .env.example。**切勿提交 .env。**在生产环境中，建议使用 Cursor 插件 Configure 界面或密钥管理器。

写入范围和任务工具

当某个范围列在 LINKWARDEN_MCP_WRITE_SCOPES 中时，服务器会为该领域注册任务工具。LINKWARDEN_MCP_DELETE_SCOPES 会为每个领域启用删除/合并工具。调用 list_resources，查看 read_only、范围列表和实时边界字符串。

仅使用推荐范围的示例：

"LINKWARDEN_MCP_WRITE_SCOPES": "links,collections",
"LINKWARDEN_MCP_DELETE_SCOPES": "links"

拒绝列表（始终阻止）： /api/v1/tokens、/api/v1/session、/api/v1/auth、/api/v1/users/**（GET /api/v1/users/me 除外）、迁移操作，以及整个实例的保存工作进程操作。

工具

读取工具

始终注册（共 18 个）。

写入工具

仅在设置了相应范围时注册（见上表）。整理收件箱时，优先使用 smart_save_link / 整理工具，而不是直接编辑字段。

Agent Skill

配套技能：skills/linkwarden-bookmarks/SKILL.md。

Cursor 插件会从 skills/ 中发现此技能。没有该插件时，请将该文件夹复制或符号链接到 Agent 技能路径。它会告知模型先调用 list_resources，写入后进行验证，以及优先使用哪些工作流工具。

开发

uv sync --extra dev
npm install          # installs lefthook + commitlint; registers git hooks
uv run linkwarden-mcp

仅运行离线测试（respx）。无需运行中的 Linkwarden：

uv run ruff check src tests
uv run pytest

Git hooks（lefthook）

提交消息必须遵循 Conventional Commits，例如 feat(api): add delete_links tool。

标记发布版本前，请运行本地发布检查：

npm run pre-publish

GitHub Actions 矩阵：Python 3.10 和 3.12。

注意事项

• 一个进程 ↔ 一个 LINKWARDEN_API_URL。多实例路由不在支持范围内。
• 共享实例上的多用户／团队消歧未经验证。在针对实时共享资料库完成验证前，请勿声称支持多租户。
• 集合／标签建议基于启发式规则，且仅限当前资料库；不会凭空创建新的标签名称。
• 批量修改工作流默认使用 dry_run=true；仅在检查计划后才设置 dry_run=false。
• ChatGPT Apps 需要托管的 HTTP MCP 端点。此软件包仅支持 stdio。

许可证

MIT。请参阅 LICENSE。