Zotero

Accede y gestiona los datos de tu biblioteca de Zotero a través de la API local o web.

Documentación

Servidor del Model Context Protocol para Zotero

Este proyecto es un servidor en Python que implementa el Model Context Protocol (MCP) para Zotero, brindándote acceso a tu biblioteca de Zotero dentro de asistentes de IA. Su objetivo es implementar un conjunto pequeño pero sumamente útil de interacciones con Zotero para usar con clientes MCP.

Características

Este servidor MCP proporciona las siguientes herramientas:

zotero_search_items: Busca elementos en tu biblioteca de Zotero usando una consulta de texto
zotero_item_metadata: Obtén los metadatos completos de un elemento específico de Zotero, cubriendo todos los campos poblados agrupados en detalles de publicación, identificadores, marcas de tiempo e información de la biblioteca
zotero_item_fulltext: Obtén el texto completo de un elemento específico de Zotero (es decir, el contenido del PDF)

Estas herramientas se pueden descubrir y acceder a través de cualquier cliente MCP o mediante el MCP Inspector.

Cada herramienta devuelve texto formateado con la información relevante de tus elementos de Zotero, y asistentes de IA como Claude pueden usarlas de forma secuencial: buscar elementos y luego recuperar sus metadatos o contenido de texto.

Instalación

Este servidor puede ejecutarse contra una API local ofrecida por la aplicación de escritorio de Zotero) o a través de la Zotero Web API. La API local puede ser un poco más receptiva, pero requiere que la aplicación de Zotero esté ejecutándose en la misma computadora con la API habilitada. Para habilitar la API local, sigue estos pasos:

Abre Zotero y abre "Configuración de Zotero"
En la pestaña "Avanzado", marca la casilla que dice "Permitir que otras aplicaciones en esta computadora se comuniquen con Zotero".

Para usar la Zotero Web API, necesitarás crear una clave de API y encontrar tu ID de biblioteca (generalmente tu ID de usuario) en la configuración de tu cuenta de Zotero aquí: https://www.zotero.org/settings/keys

Estas son las opciones de configuración disponibles:

ZOTERO_LOCAL=true: Usa la API local de Zotero (predeterminado: false, ver nota abajo)
ZOTERO_API_KEY: Tu clave de API de Zotero (no requerida para la API local)
ZOTERO_LIBRARY_ID: Tu ID de biblioteca de Zotero (tu ID de usuario para bibliotecas de usuario, no requerido para la API local)
ZOTERO_LIBRARY_TYPE: El tipo de biblioteca (user o group, predeterminado: user)

`uvx` con la API local de Zotero

Para usar esto con Claude Desktop y una instalación directa de Python con uvx, agrega lo siguiente a la configuración de mcpServers:

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

El especificador @latest es opcional y obtendrá la versión más reciente cuando haya nuevas disponibles. Si no tienes uvx instalado, puedes usar pipx run en su lugar, o clonar este repositorio localmente y usar las instrucciones en Desarrollo abajo.

Docker con la Zotero Web API

Si deseas ejecutar este servidor MCP en un contenedor Docker, puedes usar la siguiente configuración, insertando tu clave de API y tu ID de biblioteca:

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

Para actualizar a una versión más reciente, ejecuta docker pull ghcr.io/kujenga/zotero-mcp:main. También es posible usar la instalación basada en Docker para comunicarte con la API local de Zotero, pero necesitarás modificar el comando anterior para asegurar que haya conectividad de red con la interfaz de la API local de la aplicación de Zotero.

Desarrollo

Información sobre cómo hacer cambios y contribuir al proyecto.

Clona este repositorio
Instala las dependencias con uv ejecutando: uv sync
Crea un archivo .env en la raíz del proyecto con las variables de entorno anteriores

Inicia el MCP Inspector para el desarrollo local:

npx @modelcontextprotocol/inspector uv run zotero-mcp

Para probar el repositorio local contra Claude Desktop, ejecuta echo $PWD/.venv/bin/zotero-mcp en tu shell dentro de este directorio, y luego configura lo siguiente en tu configuración de Claude Desktop:

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

Ejecutar pruebas

Para ejecutar la suite de pruebas:

uv run pytest

Publicar versiones

Incrementa la versión en pyproject.toml y server.json (dos lugares: la versión del servidor y la versión del paquete).
Publica en PyPI con make publish.
Publica los metadatos actualizados en el registro oficial de MCP con make publish-mcp, authenticating first with mcp-publisher login github si es necesario.

Desarrollo con Docker

Construye la imagen del contenedor con este comando:

docker build . -t zotero-mcp:local

Para probar el contenedor con el inspector MCP, ejecuta el siguiente comando:

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

Documentación relevante

Apéndice: notas sobre la API de Zotero

Los metadatos de los elementos se generan a partir de los campos que devuelve la API, en lugar de una lista fija. Los campos que omite se omiten, y los campos que este servidor no conoce aparecen bajo un encabezado "Otros campos", por lo que una actualización de Zotero nunca elimina metadatos silenciosamente.

Las dos APIs difieren en un aspecto que vale la pena conocer: la búsqueda rápida de la API local indexa las claves de citación, mientras que la Web API no lo hace, por lo que buscar una de ellas no devuelve nada a través de la Web API, aunque el campo esté presente en los datos.