Linkwarden

io.github.ni-c由 GitHub 帳號 ni-c 發布v0.4.0更新於 Oct 24, 2026

MCP server for Linkwarden, the self-hosted bookmark manager with page preservation

已驗證STDIO僅桌面效率與工作流知識與記憶

概覽

AI 產生的概覽

針對自架 Linkwarden 執行個體的 MCP 伺服器:搜尋書籤、讀取已保存網頁的封存正文,並整理連結、收藏集與標籤。

可以做什麼
  • 依欄位篩選搜尋與列出書籤,並取得單一連結的標籤、所屬收藏集與已封存格式
  • 讀取已保存網頁的封存正文(長文會分段),以及儀表板和 RSS 訂閱
  • 檢視收藏集、標籤與目前帳號,管理員還可查看封存與搜尋索引佇列
  • 儲存、更新、置頂、批次修改或刪除書籤,並重新封存或刪除封存副本
  • 建立、重新命名、調整層級、發布或刪除收藏集,以及建立、重新命名、合併或刪除標籤
  • 訂閱或取消 RSS/Atom 來源
適用情境
適合已用 Linkwarden 收藏書籤、希望助理在對話中尋找已儲存的連結、對即使原網站已變更仍可引用的封存頁面做摘要或引用,並順手整理標籤與收藏集的情境。
執行需求
透過 npx 或容器映像以 stdio 在本機執行;npm 套件需要 Node.js 24 或更新版本。需要一個執行中的 Linkwarden 執行個體,並設定 LINKWARDEN_URL(不含 /api/v1 的基礎網址)以及在「設定 → 存取權杖」建立的權杖 LINKWARDEN_TOKEN。選用變數可篩選工具、強制唯讀模式或接受自簽憑證。
安裝前請注意
權杖擁有建立它的帳號的全部權限,建議改用權限受限的專用帳號。寫入類工具會修改或刪除書籤、封存、標籤與收藏集,刪除收藏集會連帶刪除其中的連結;破壞性操作會要求真人確認,設定 LINKWARDEN_READ_ONLY 則只註冊讀取工具。儲存的網址會由 Linkwarden 的瀏覽器抓取,因此內網位址仍可被存取。封存正文屬於不可信的第三方內容。請使用 https,以免權杖以明文傳輸。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Linkwarden,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

linkwarden-mcp

[CI] [OpenSSF Scorecard] [Socket Badge] [Glama score]
[npm version] [container image] [HTTP via mcp-hub]
[docs] [sponsor]

A Model Context Protocol (MCP) server for Linkwarden, the self-hosted bookmark manager that keeps a permanent copy of every page it saves.

Lets MCP clients like Claude Code, Claude Desktop or Codex search a bookmark collection, organise it into collections and tags, and read the preserved article text of a saved page, so a link that has been archived can be summarised or quoted without fetching the live site again.

Twenty-eight tools is the ceiling, not the floor: LINKWARDEN_ALLOW_TOOLS=essential registers a curated eight instead, and a model picks the right tool far more reliably from eight than from twenty-eight — see choosing which tools load.

[Demo]

[An MCP client speaks stdio to linkwarden-mcp, which calls the Linkwarden REST API over HTTPS; Linkwarden stores bookmarks and preserved copies of pages]

Note: Linkwarden's published API reference is incomplete. This server was written against the routes in apps/web/pages/api/v1/** and the request schemas in packages/lib/schemaValidation.ts of linkwarden/linkwarden, verified against v2.16.0 on 2026-08-17. Those two files are the source of truth for every tool here.

What makes it different

Reads what Linkwarden preserved. Linkwarden keeps a permanent copy of every page it saves. get_link_content serves that article text, so a saved link can be summarised or quoted without fetching the live site again — and long articles are sliced, not dumped.

Organises without clobbering. Linkwarden's update routes replace whole records. This server reads the current state and merges, so changing a title never silently strips a link's tags or a collection's collaborators.

Output is an allowlist. Linkwarden returns whole Prisma rows; every field in a result here is named explicitly. Article text stays out of list results, collection members' names and e-mail addresses are dropped, and a column added by a future release cannot land in the model's context unannounced.

Requirements

  • Node.js ≥ 24
  • A running Linkwarden instance
  • An access token, created under Settings → Access Tokens

Linkwarden has no per-token scopes: a token carries the full permissions of the account that created it. Create a dedicated account with access only to the collections this server should see rather than handing it an admin token.

Configuration

VariableRequiredDescription
LINKWARDEN_URLyesBase URL, e.g. https://links.example.net (without /api/v1)
LINKWARDEN_TOKENyesAccess token from Settings → Access Tokens
LINKWARDEN_READ_ONLYnotrue registers only the read tools
LINKWARDEN_ALLOW_TOOLSnoComma-separated tool names, list_* prefixes, or essential for a curated preset
LINKWARDEN_DENY_TOOLSnoSame syntax; removed from whatever LINKWARDEN_ALLOW_TOOLS left
ELICITATIONnofalse replaces the approval dialog with the two-call token. Not prefixed
LINKWARDEN_INSECURE_TLSnotrue accepts self-signed certificates (scoped to this connection)

Use https://. Over plain http the token travels unencrypted; the server prints a warning unless the host is local. For a self-signed certificate prefer a proper internal CA over LINKWARDEN_INSECURE_TLS.

The token is removed from the process environment once it has been read, so it is not visible to child processes or in /proc/<pid>/environ.

Without credentials the server still starts and lists its tools, so registries and inspectors can introspect it; every call then fails with setup instructions instead of reaching the API.

Choosing which tools load

LINKWARDEN_ALLOW_TOOLS and LINKWARDEN_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of eight — save, find and read — marked as such in the tool reference.

sh
LINKWARDEN_ALLOW_TOOLS=essentialLINKWARDEN_ALLOW_TOOLS=search_links,get_link_content,create_linkLINKWARDEN_DENY_TOOLS=bulk_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under LINKWARDEN_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

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

Claude Desktop

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

Codex

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

From source

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

Docker

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

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches linkwarden-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

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

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose. Seven tools that answered with a sentence — "Link 42 deleted." — now answer with the fields as well, and the sentence stays in the text block.

The ten reading tools carry untrusted: true and source: "linkwarden" as fields. Bookmark titles, descriptions and above all the preserved article text are written by whoever controls the target site; this server has always said so in notes, which is prose a client can read but not check, and the field is what makes it checkable. The write tools are without it: they report an id this server was given and a count it made.

An over-budget result still drops list entries, and an oversized untrusted envelope still loses characters from its largest field. Where neither leaves anything to give it is now an error rather than an envelope carrying the oversized document as a string: that envelope is valid JSON and not a valid answer, since the SDK checks a result against the schema its tool declares.

Reading

ToolDescription
search_linksSearch or list bookmarks. Supports Linkwarden's field filters (tag:, collection:, before:, ! …).
get_linkOne bookmark with its tags, collection and which preserved formats exist.
get_link_contentThe preserved article text of a saved page, sliced for long articles.
list_collectionsAll collections with link counts; nesting via parentId.
get_collectionOne collection with its per-member permissions.
list_tagsTags with link counts and their per-tag archival settings.
get_tagOne tag.
get_dashboardRecently added plus pinned links, as Linkwarden's dashboard shows them.
list_rss_subscriptionsThe RSS feeds this account subscribes to.
get_current_userWhich account the token belongs to, and its archival defaults. Good connectivity check.
get_worker_statsPreservation and search-index queue. Administrator account only — everyone else gets HTTP 403.

Writing

Not registered at all when LINKWARDEN_READ_ONLY=true. Tools marked 👤 ask a person through MCP elicitation — a dialog the model cannot answer on its behalf — and fall back to a two-call confirm_token where the client cannot show one. See Asking a person.

ToolDescription
create_linkSave a bookmark, optionally with tags and a collection (created on demand).
update_linkChange title, description, tags or collection. 👤 only when the URL changes.
set_link_pinnedPin or unpin a link for this account.
delete_link 👤Delete a bookmark and its preserved copies.
bulk_update_links 👤Apply one tag list and/or collection to many links.
bulk_delete_links 👤Delete many bookmarks at once.
represerve_link 👤Drop the existing archives and preserve the page again.
delete_link_preservations 👤Drop the archives of several links, keeping the bookmarks.
create_collectionCreate a collection, optionally nested.
update_collectionRename, re-parent or publish a collection. 👤 only when publishing.
delete_collection 👤Delete a collection — cascades to its links and sub-collections.
create_tagsCreate tags or change their archival settings (upsert by name).
rename_tag 👤Rename a tag — every link that carries it follows.
delete_tags 👤Delete tags; the links keep existing.
merge_tags 👤Fold several tags into one new tag.
create_rss_subscriptionSubscribe to an RSS/Atom feed.
delete_rss_subscription 👤Stop polling a feed.

Not exposed, on purpose

  • Access-token management (/tokens). A tool that can mint API credentials is a privilege-escalation surface, and a bookmark server has no business holding one.
  • User administration (/users, account deletion). Out of scope.
  • Backup export and import (/migration). The export dumps the whole instance into the model's context; the import can destroy it.
  • Highlights. Creating one needs exact character offsets into the preserved document, which a model cannot produce meaningfully, and Linkwarden offers no route to list existing highlights.
  • Archive uploads and the signed preserved URLs, which need NEXT_PUBLIC_USER_CONTENT_DOMAIN to be configured.
  • The deprecated GET /links listing route — search_links uses GET /search instead, which is what Linkwarden itself recommends.

Safety

  • Destructive tools ask a person. Where the client supports MCP elicitation they raise a real dialog that the model cannot answer on its behalf. Where it does not, the first call returns a short-lived token bound to the exact target and only a second call carrying it performs the operation — which proves the call was made twice with the same arguments and nothing more, and the text says so. An approval issued for one link, tag set or change cannot be replayed for another. ELICITATION=false takes that fallback deliberately; it never removes the guard.
  • Losing something is not only deletion. Publishing a collection, changing a link's URL — which deletes every preserved copy of the old page — and renaming a tag, which follows every link that carries it, are all asked about.
  • Confirmation prompts never quote content from Linkwarden. Titles, URLs, descriptions and collection names come from saved pages and from other users of the instance; only counts and ids appear in the text a model reads.
  • Bookmarked URLs are checked before Linkwarden fetches them. create_link, update_link and create_rss_subscription hand a URL to a server that opens it in a headless browser — and get_link_content reads the result back, which makes an unchecked URL a way to read from inside Linkwarden's network. Loopback and link-local addresses, including the cloud metadata endpoints and their hostnames, are refused; addresses are compared numerically, so an IPv4-mapped literal such as [::ffff:169.254.169.254] is caught too, and a hostname is resolved before it is accepted. Private LAN addresses stay allowed — bookmarking the router's interface or an intranet page is a normal thing to do with a self-hosted bookmark manager, which also means a container beside Linkwarden is reachable; SECURITY.md says what the check does and does not cover, including the entries inside an RSS feed.
  • Returned content is marked as untrusted data, in particular the preserved article text, which is written by whoever controls the target site.
  • Partial updates never clear fields. Linkwarden's update routes replace the whole record, so this server reads the current state and merges — otherwise an update would silently strip a link's tags or a collection's collaborators.
  • A 200 is not trusted on its own. Several Linkwarden routes report failures with HTTP 200 and an error sentence in the body, and a route without a handler for the method used answers 200 with nothing at all. Both are reported as errors rather than as a successful write.
  • Error bodies are truncated, HTML error pages are dropped entirely, redirects are never followed (so the bearer token cannot be replayed to another host), and every request carries a timeout.
  • LINKWARDEN_READ_ONLY=true does not register the write tools at all.
  • Residual risk: within the permissions of the token you configure, a model that is asked to do something destructive and is confirmed by a user can still do it. Scope the account, and keep host-level permission prompts on.

Documentation

The full guide, tool reference and security notes live at linkwarden-mcp.ni-c.de (source in docs/).

Development

sh
npm installnpm run buildnpm testnpm run test:coveragenpm run lintnpm run formatnpm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md is generated; CI fails if the committed copy no longer matches the code. The documentation site lives in docs/ with its own package.json and lockfile — VitePress must not end up in the root install, which runs in the Docker build and across the whole test matrix.

See CONTRIBUTING.md.

Releasing

Everything is driven by a tag; there is no manual publish step.

  1. Move the [Unreleased] section of CHANGELOG.md to the new version and date it. The release workflow extracts that section with awk, so the ## [x.y.z] heading shape matters.

  2. Bump version in package.json.

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

  4. Commit, then a signed annotated tag:

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

release.yml then verifies the tag matches package.json, publishes to npm over Trusted Publishing (OIDC — no npm token exists to leak) with provenance, syncs the version into both server.json package entries, publishes to the MCP registry, and cuts the GitHub release from the changelog section. ci.yml pushes the multi-arch container image to GHCR in parallel.

If the registry step fails, fix it on main and run the mcp-registry.yml workflow by hand. Re-running the failed job is not an option: it checks out the immutable tag, so a fix on main could never reach it.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel

來源:README.md,提交 e90f5b4

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.4.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分