Модель сервера контекстного протокола для Zotero

Этот проект представляет собой сервер Python, реализующий протокол контекста модели (MCP) для Zotero , предоставляя вам доступ к вашей библиотеке Zotero в помощниках AI. Он предназначен для реализации небольшого, но максимально полезного набора взаимодействий с Zotero для использования с клиентами MCP .

Функции

Этот сервер MCP предоставляет следующие инструменты:

• zotero_search_items : Поиск элементов в вашей библиотеке Zotero с помощью текстового запроса

• zotero_item_metadata : Получить подробную информацию о метаданных определенного элемента Zotero

• zotero_item_fulltext : Получить полный текст определенного элемента Zotero (т. е. содержимое PDF)

Их можно обнаружить и получить к ним доступ через любой клиент MCP или через MCP Inspector .

Каждый инструмент возвращает форматированный текст, содержащий соответствующую информацию из ваших элементов Zotero, а помощники на основе искусственного интеллекта, такие как Клод, могут использовать их последовательно, выполняя поиск элементов, а затем извлекая их метаданные или текстовое содержимое.

Related MCP server: Zotero MCP Server

Установка

Этот сервер может работать либо с локальным API, предлагаемым приложением Zotero для настольных компьютеров , либо через Zotero Web API . Локальный API может быть немного более отзывчивым, но требует, чтобы приложение Zotero было запущено на том же компьютере с включенным API. Чтобы включить локальный API, выполните следующие действия:

1. Откройте Zotero и откройте «Настройки Zotero».

2. На вкладке «Дополнительно» установите флажок «Разрешить другим приложениям на этом компьютере взаимодействовать с Zotero».

[!ВАЖНО] Для доступа к конечной точке /fulltext на локальном API, которая позволяет извлекать полное содержимое элементов в вашей библиотеке, вам необходимо установить сборку Zotero Beta (по состоянию на 2025-03-30). После выпуска версии 7.1 это больше не будет иметь места. Для получения дополнительной информации см. https://github.com/zotero/zotero/pull/5004 . Если вы не хотите этого делать, используйте вместо этого веб-API.

Чтобы использовать Zotero Web API, вам необходимо создать ключ API и найти свой идентификатор библиотеки (обычно это ваш идентификатор пользователя) в настройках вашей учетной записи Zotero здесь: https://www.zotero.org/settings/keys

Доступны следующие варианты конфигурации:

• ZOTERO_LOCAL=true : использовать локальный API Zotero (по умолчанию: false, см. примечание ниже)

• ZOTERO_API_KEY : Ваш ключ API Zotero (не требуется для локального API)

• ZOTERO_LIBRARY_ID : Ваш идентификатор библиотеки Zotero (ваш идентификатор пользователя для пользовательских библиотек, не требуется для локального API)

• ZOTERO_LIBRARY_TYPE : Тип библиотеки (пользователь или группа, по умолчанию: пользователь)

uvx с локальным API Zotero

Чтобы использовать это с Claude Desktop и прямой установкой Python с uvx , добавьте следующее в конфигурацию mcpServers :

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--upgrade", "zotero-mcp"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

Флаг --upgrade необязателен и будет загружать последнюю версию, когда появятся новые. Если у вас не установлен uvx , вы можете использовать pipx run вместо этого или клонировать этот репозиторий локально и использовать инструкции в разделе «Разработка» ниже.

Docker с Zotero Web API

Если вы хотите запустить этот сервер MCP в контейнере Docker, вы можете использовать следующую конфигурацию, вставив свой ключ API и идентификатор библиотеки:

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ],
    }
  }
}

Для обновления до новой версии запустите docker pull ghcr.io/kujenga/zotero-mcp:main . Также можно использовать установку на основе docker для взаимодействия с локальным API Zotero, но вам нужно будет изменить указанную выше команду, чтобы обеспечить сетевое подключение к локальному интерфейсу API приложения Zotero.

Разработка

Информация о внесении изменений и участии в проекте.

1. Клонировать этот репозиторий

2. Установите зависимости с помощью uv , выполнив: uv sync

3. Создайте файл .env в корне проекта с указанными выше переменными среды.

Запустите MCP Inspector для локального развития:

npx @modelcontextprotocol/inspector uv run zotero-mcp

Чтобы протестировать локальный репозиторий с помощью Claude Desktop, запустите echo $PWD/.venv/bin/zotero-mcp в своей оболочке в этом каталоге, затем установите следующее в конфигурации Claude Desktop:

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
      "env": {
        // Whatever configuration is desired.
      }
    }
  }
}

Проведение тестов

Чтобы запустить тестовый набор:

uv run pytest

Разработка Докера

Создайте образ контейнера с помощью этой команды:

docker build . -t zotero-mcp:local

Чтобы протестировать контейнер с помощью MCP-инспектора, выполните следующую команду:

npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local

Соответствующая документация

• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

• https://github.com/modelcontextprotocol/python-sdk

• https://pyzotero.readthedocs.io/en/latest/

• https://www.zotero.org/support/dev/web\_api/v3/start

• https://modelcontextprotocol.io/llms-full.txt может использоваться LLM