linkwarden-mcp

Сервер Model Context Protocol для Linkwarden — самостоятельного менеджера закладок, который хранит постоянную копию каждой сохранённой страницы.

Он позволяет MCP-клиенту (Claude Code, Claude Desktop, Codex) искать коллекцию закладок, организовывать её по коллекциям и тегам, а также читать сохранённый текст статьи сохранённой страницы, чтобы дать ссылку, которая была заархивирована, можно было суммировать или цитировать без повторного обращения к живому сайту.

📖 Полная документация на linkwarden-mcp.ni-c.de

Примечание: Опубликованная ссылка на API Linkwarden неполная. Этот сервер был написан на основе маршрутов из apps/web/pages/api/v1/** и схем запросов из packages/lib/schemaValidation.ts репозитория linkwarden/linkwarden, проверен на v2.16.0 2026-08-17. Эти два файла являются источником истины для каждого инструмента здесь.

Требования

• Node.js ≥ 22

• Работающий экземпляр Linkwarden

• Токен доступа, созданный в Settings → Access Tokens

В Linkwarden нет разрешений для отдельных токенов: токен несёт все разрешения учётной записи, которая его создала. Создайте выделенную учётную запись с доступом только к тем коллекциям, которые должен видеть этот сервер, вместо того чтобы передавать ему токен администратора.

Related MCP server: linkwarden-mcp

Конфигурация

Используйте https://. По обычному http токен передаётся в незашифрованном виде; сервер выводит предупреждение, если хост не локальный. Для самоподписанного сертификата предпочтительнее использовать собственный внутренний ЦС, а не 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). Экспорт выгружает весь экземпляр в контекст модели; импорт может его уничтожить.

• Выделения (highlight). Для создания нужно точное смещение символов в сохранённом документе, которое модель не может осмысленно создать, и Linkwarden не предоставляет маршрута для списка существующих выделений.

• Загрузка архивов и подписанные URL preserved, которые требуют настройки NEXT_PUBLIC_USER_CONTENT_DOMAIN.

• Устаревший маршрут списка GET /links — search_links использует вместо него GET /search, который рекомендует сам Linkwarden.

Безопасность

• Деструктивные инструменты являются двухэтапными. Первый вызов возвращает кратковременный токен подтверждения, привязанный к точной цели; только второй вызов с этим токеном выполняет операцию. Модель не может пройти эту проверку самостоятельно, и токен, выданный для одной ссылки, набора тегов или изменения, не может быть повторно использован для другого.

• Расширение видимости считается деструктивным. Публикация коллекции и изменение URL ссылки — что удаляет все сохранённые копии старой страницы — оба требуют подтверждения, а не только удаления.

• Подсказки подтверждения никогда не цитируют содержимое из Linkwarden. Заголовки, URL, описания и названия коллекций берутся из сохранённых страниц и от других пользователей экземпляра; в тексте, который читает модель, отображаются только количества и идентификаторы.

• Возвращаемое содержимое помечается как ненадёжные данные, в частности сохранённый текст статьи, который написан тем, кто контролирует целевой сайт.

• Частичные обновления никогда не очищают поля. Маршруты обновления Linkwarden заменяют всю запись, поэтому этот сервер читает текущее состояние и выполняет слияние — иначе обновление незаметно удалило бы теги ссылки или участников коллекции.

• Статус 200 не считается сам по себе надёжным. Несколько маршрутов Linkwarden сообщают об ошибках с HTTP 200 и предложением ошибки в теле, а маршрут без обработчика для используемого метода отвечает 200 с пустым телом. И то, и другое сообщается как ошибка, а не как успешная запись.

• Тела ошибок обрезаются, HTML-страницы ошибок полностью отбрасываются, перенаправления никогда не выполняются (чтобы токен не мог быть повторно использован для другого хоста), и каждый запрос имеет таймаут.

• 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. Переместите раздел [Unreleased] из CHANGELOG.md в новую версию и укажите дату. Рабочий процесс релиза извлекает этот раздел с помощью awk, поэтому формат заголовка ## [x.y.z] важен.

2. Обновите version в package.json.

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, публикует в npm через Trusted Publishing (OIDC — никакой npm-токен не существует для утечки) с подтверждением происхождения, синхронизирует версию в обе записи пакета server.json, публикует в реестр MCP и создает GitHub-релиз из раздела changelog. ci.yml параллельно отправляет многоархитектурный образ контейнера в GHCR.

Если шаг с реестром завершится ошибкой, исправьте её в main и запустите рабочий процесс mcp-registry.yml вручную. Повторный запуск неудачной задачи невозможен: она проверяет неизменяемый тег, поэтому исправление в main никогда не сможет до него добраться.

Лицензия

MIT © Willi Thiel