linkwarden-mcp

Model Context Protocol サーバーです。 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 のリクエストスキーマに対して作成され、 v2.16.0 (2026-08-17) で検証されています。これら 2 つのファイルが、ここにあるすべてのツールの信頼できる情報源です。

要件

• Node.js ≥ 22

• 実行中の Linkwarden インスタンス

• 設定 → アクセストークン で作成されたアクセストークン

Linkwarden にはトークンごとのスコープはありません。トークンは、それを作成したアカウントのすべての権限を持ちます。管理トークンを渡すのではなく、このサーバーがアクセスすべきコレクションのみにアクセスできる専用アカウントを作成してください。

Related MCP server: linkwarden-mcp

設定

https:// を使用してください。 平文の http ではトークンが暗号化されずに送信されます。ホストがローカルでない限り、サーバーは警告を出力します。自己署名証明書の場合は、LINKWARDEN_INSECURE_TLS よりも適切な内部 CA を推奨します。

トークンは読み取り後にプロセス環境から削除されるため、子プロセスや /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 自身が推奨する方法です。

安全性

• 破壊的なツールは 2 段階です。 最初の呼び出しは、正確な対象に紐づいた短命の確認トークンを返します。そのトークンを使って 2 回目の呼び出しを行うことで初めて操作が実行されます。モデル単独ではこのゲートを通過できず、あるリンク、タグセット、変更に対して発行されたトークンを別のものに使い回すことはできません。

• 可視性の拡大は破壊的とみなされます。 コレクションの公開や、リンクの 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](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 の両方のパッケージエントリに同期し、MCPレジストリに公開し、チェンジログセクションからGitHubリリースを作成します。ci.yml はそれと並行してマルチアーキテクチャコンテナイメージをGHCRにプッシュします。

レジストリ手順が失敗した場合は、main ブランチで修正し、mcp-registry.yml ワークフローを手動で実行してください。失敗したジョブの再実行はオプションではありません。不変のタグをチェックアウトするため、main での修正がそこに届くことは決してありません。

ライセンス

MIT © Willi Thiel