Zotero Web MCP

Локальный MCP-сервер для Claude Desktop поверх официального Zotero Web API v3. Собственная реализация, не форк стороннего Zotero MCP. Node.js 22+, без npm-зависимостей, без сборки.

Claude Desktop → stdio → node src/server.mjs → HTTPS → api.zotero.org
                                                   ↕ синхронизация
                                               Zotero Desktop

Статус: 0.1.0, первоначальная реализация для проверки на тестовой коллекции. Модульные тесты, тесты защиты и запуск реального MCP-процесса проверяются автоматически. Работа с настоящим аккаунтом Zotero, настоящие загрузки файлов и установка в Windows/Claude Desktop еще требуют проверки. Нельзя считать успешные mock-тесты подтверждением этих интеграций.

Быстрая установка в Windows

1. Проверьте node --version: нужна версия 22 или новее.

2. Скачайте/распакуйте исходники в постоянную папку. После публикации в GitHub вместо ZIP можно использовать git clone <URL-репозитория>.

3. В аккаунте Zotero создайте отдельный API key: https://www.zotero.org/settings/keys. Дайте доступ к нужной библиотеке, заметкам, файлам и записи. Не включайте все группы без необходимости.

4. Полностью закройте Claude Desktop, включая значок в системном трее.

5. Запустите setup-windows.cmd. Вставьте ключ в скрытое поле терминала, выберите папку обмена, подтвердите запись.

6. Откройте Claude Desktop заново и проверьте инструмент zotero_status.

setup-windows.cmd последовательно выполняет настройку, реальную проверку чтения библиотеки и добавление только записи zotero-web в конфигурацию Claude. Предварительно создается резервная копия. Другие MCP, в том числе Obsidian, не заменяются.

npm install, npx, Python, Docker, VPS и открытый сетевой порт не нужны. Node запускается непосредственно. npm используется только как удобный запускатель локальных скриптов; его тоже можно обойти.

Пошаговая инструкция, настройка вручную, тесты и устранение ошибок: Windows setup.

Related MCP server: zotero-mcp

Что реализовано

28 инструментов дают доступ к библиотечным операциям API, а не только к нескольким полям:

• поиск и чтение записей, коллекций, тегов, заметок и аннотаций; пагинация, версии, сортировка и документированные фильтры;

• создание и изменение записей всех поддерживаемых Zotero типов через editable JSON, авторов, связей, коллекций/подколлекций, тегов и сохраненных поисков;

• пакетные операции до 50 объектов с отдельным отчетом об успехах и ошибках;

• чтение/запись синхронизированного полнотекстового индекса, экспорт BibTeX/BibLaTeX, CSL JSON, RIS и других поддерживаемых форматов;

• загрузка локальных файлов в Zotero Storage, скачивание доступных облачных вложений, замена с проверкой MD5 и продвинутый binary-diff upload;

• корзина, восстановление, постоянное удаление и синхронизируемые настройки с дополнительными ограничениями;

• поиск кандидатов в дубликаты без автоматического объединения.

Полный список, соответствие конечным точкам и ограничения: CAPABILITIES.

Это не заявление о полном совпадении с любым общественным Zotero MCP и не универсальный доступ ко всем сервисам Zotero. Здесь нет GUI-управления, самостоятельного поиска PDF у издателей, OCR, семантического векторного индекса, автоматического DOI-распознавания или нативного merge дубликатов. Аккаунты, создание/удаление API-ключей, участники групп и платежи не управляются.

Где хранится ключ

На Windows: %APPDATA%\zotero-web-mcp\config.json.

Ключ находится вне репозитория, в локальном JSON с ограничением прав доступа. Файл не зашифрован. В конфигурацию Claude помещается только путь к нему, не сам ключ. Установщик получает цифровой User ID через авторизованный keys/current; вручную переписывать его не требуется.

В src/ нет инструментов оболочки, запуска программ или чтения произвольных URL. Входящие HTTP-подключения не принимаются; телеметрии и автообновления нет. Для обмена файлами используется отдельная папка, а не весь диск. HTTPS-ключ отправляется только api.zotero.org; хранилище файлов получает только выданные Zotero параметры загрузки.

Это ограничения данного MCP, не песочница для всех остальных инструментов Claude. Подробнее: SECURITY.

Опасные операции

Постоянное удаление, перемещение в корзину, PUT-перезапись объекта, публикационный статус и изменение синхронизированных настроек сначала создают локальный план. dryRun: true позволяет подготовить план и для обычной записи.

Человек проверяет план в терминале:

npm.cmd run approve -- <planId>

Затем вручную вводит полный ID плана и просит Claude вызвать zotero_execute_plan. Подтверждение привязано к содержимому, действует 30 минут и используется однократно. Сам MCP не предоставляет Claude инструмента одобрения. Нельзя поручать другому агентному shell-инструменту выполнять это одобрение за человека.

Обычные добавления/правки/импорт при разрешенной записи выполняются без локального подтверждения. Они тоже могут ошибочно изменить важные данные: читайте модель безопасности, используйте тестовую коллекцию и резервную копию Zotero до массовой обработки.

Команды

npm.cmd run setup
npm.cmd run doctor
npm.cmd run install:claude
npm.cmd test
npm.cmd run check

Эквиваленты без npm:

node scripts/setup.mjs
node scripts/doctor.mjs
node scripts/install-claude.mjs
node scripts/test.mjs
node scripts/check.mjs

npm.cmd run uninstall:claude удаляет только запись подключения. Приватный конфиг и библиотека не удаляются. Чтобы окончательно отозвать доступ, отзовите ключ в Zotero; затем удалите локальный конфиг самостоятельно.

Claude, Obsidian и Overleaf

Skill не нужен для самого подключения: инструменты содержат схемы и описания. Дополнительный необязательный skill лежит в skills/zotero-library/SKILL.md. Пример небольшого дополнения к общим инструкциям: CLAUDE-INSTRUCTIONS.ru.txt. Не заменяйте им существующие правила Obsidian или Overleaf. PDF/записи остаются в Zotero, итоговые рабочие заметки — в Obsidian, .bib и документ — в Overleaf по задаче пользователя.

Разработка и проверка

Собственный минимальный JSON-RPC/MCP stdio transport реализует initialization, ping, tools/list, tools/call и отмену запросов. Объявляются только поддерживаемые capabilities. Ресурсы, sampling, tasks, HTTP transport и полный SDK не реализованы и не объявляются.

Поддерживаемые версии протокола: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. При другой версии сервер предлагает поддерживаемую; окончательная совместимость зависит от клиента.

Отчет и ограничения тестирования. В CI предусмотрены Linux/Windows и Node 22/24; само наличие workflow не означает, что GitHub Actions уже запускался.

Первичные источники

Реализация написана самостоятельно по официальным интерфейсам; чужой Zotero MCP не включен.

• Zotero Web API basics

• Editable JSON, создание/правка/удаление

• File upload/download и binary patches

• Синхронизация

• Типы и поля

• Официальный sync API client Zotero, сведения о fulltext/settings/keys/current

• MCP lifecycle, stdio, tools

• Локальные MCP в Claude Desktop

MIT. Неофициальный проект, не связан с Zotero или Anthropic.