Hardcover MCP

Habla con tu biblioteca de Hardcover desde cualquier asistente de IA.

Documentación

hardcover-mcp

Habla con tu biblioteca de Hardcover desde cualquier asistente de IA.

hardcover-mcp conecta tu biblioteca de Hardcover con asistentes de IA como Claude y Copilot. Busca libros, actualiza tu estado de lectura, gestiona listas, explora series: todo mediante conversación natural en lugar de hacer clic en menús.

Lo que puedes decir

"¿Qué hay en mi lista de lectura actual?"

"Añade Project Hail Mary a mi biblioteca como lectura actual"

"Busca libros de Brandon Sanderson"

"Busca el ISBN 9780547928227"

"Crea una lista llamada 'Summer Reading' y añade The Hobbit"

"Muéstrame la serie Stormlight Archive en orden de lectura"

"Mueve Project Hail Mary y The Martian a lectura actual"

"¿Qué libros ha escrito Andy Weir? Añade los que no haya leído a mi lista de quiero leer"

"Compara mi calificación de Dune con el promedio de Hardcover"

Lo que está cubierto

Seguimiento de biblioteca — estado, calificaciones, fechas de lectura
Gestión de listas — crear, editar, añadir/eliminar libros
Descubrimiento — buscar libros, autores, series, ediciones y más
Información de cuenta — tu perfil y estadísticas de lectura

Seguridad y control

Tú controlas tu clave API — permanece en tu máquina, nunca se comparte con terceros
Se ejecuta localmente a través de tu cliente MCP — no hay servidor externo involucrado
Las acciones solo ocurren cuando se solicitan explícitamente — nada se ejecuta en segundo plano
Revisas las indicaciones y salidas en tu cliente antes de que se envíe algo

Inicio rápido

Instala uv (un ejecutor de paquetes de Python rápido: la configuración toma segundos).
Obtén un token de API de hardcover.app/account/api.
Añade la configuración a continuación a tu cliente MCP: no se necesita instalación manual, uvx se encarga de ello.

VS Code

Añade a .vscode/mcp.json:

{
  "servers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>"
      }
    }
  }
}

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>"
      }
    }
  }
}

Herramientas

Explorar y descubrir

Lo que puedes hacer	Herramienta
Buscar libros, autores, series y más	`search_books`
Buscar un libro por título o ID	`get_book`
Buscar una edición específica por ISBN o ASIN	`get_edition`
Explorar una serie en orden de lectura	`get_series`
Navegar por el catálogo de un autor	`get_author`

Tu biblioteca

Lo que puedes hacer	Herramienta
Ver tu perfil y recuento de libros	`me`
Obtener estadísticas de lectura (totales, calificaciones, libros leídos por año)	`get_reading_stats`
Obtener tus metas de lectura activas y su progreso	`get_reading_goal`
Explorar tu biblioteca, filtrar por estado, rango de fechas u ordenar por calificación/fecha	`get_user_library`
Consultar tu estado/calificación de un libro específico (incluye configuración de privacidad)	`get_user_book`
Listar tus reseñas	`get_user_reviews`
Leer tus entradas de diario (notas, citas, eventos de estado)	`get_reading_journal`
Listar los libros que posees, con detalles de edición	`get_owned_books`
Crear o actualizar una meta de lectura (libros/páginas, rango de fechas)	`set_reading_goal`
Añadir un libro o actualizar su estado, calificación, reseña, notas, privacidad y edición	`set_user_book`
Marcar una edición como poseída o no poseída	`set_edition_owned`
Registrar fechas de lectura y progreso (páginas, tiempo de audiolibro)	`add_user_book_read` / `update_user_book_read`
Eliminar un libro o una entrada de lectura	`delete_user_book` / `delete_user_book_read`
Crear o eliminar una entrada de nota/cita de diario	`add_journal_entry` / `delete_journal_entry`

Listas

Lo que puedes hacer	Herramienta
Ver todas tus listas	`get_my_lists`
Ver una lista específica con sus libros	`get_list`
Crear, renombrar o eliminar una lista	`create_list` / `update_list` / `delete_list`
Añadir o eliminar libros de una lista	`add_book_to_list` / `remove_book_from_list`

Desarrollo

git clone https://github.com/kristianedlund/hardcover-mcp.git
cd hardcover-mcp
uv sync

Comprobaciones de lint y formato (usando Ruff):

uv run ruff check src/
uv run ruff format --check src/

Ejecutar pruebas:

uv run pytest tests/ -v

Pruebas de integración

Las pruebas de integración acceden a la API de Hardcover en vivo y requieren un token válido. Se omiten automáticamente en CI y cuando el token no está presente.

Para ejecutarlas localmente, crea un archivo .env con tu token:

HARDCOVER_API_TOKEN=your_token_here

Luego ejecuta:

uv run pytest tests/integration/ -v

Las pruebas de escritura siguen un ciclo de vida de crear → verificar → eliminar para que la cuenta quede sin cambios.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Abre un issue primero para discutir el cambio.
Haz un fork del repositorio y crea una rama (feature/short-description o fix/short-description).

Ejecuta lint y pruebas antes de enviar:

uv run ruff check src/
uv run ruff format --check src/
uv run pytest tests/ -v

Mantén los PR enfocados: un cambio por PR.
Usa prefijos de commit convencionales: feat:, fix:, chore:, docs:.

Límite de velocidad

La API de Hardcover permite 60 solicitudes por minuto. El servidor maneja esto automáticamente: pone en cola las solicitudes y reintenta si es necesario. No deberías alcanzar este límite en uso normal.

Solución de problemas

Problema	Solución
"El token de API no está configurado"	Añade tu token a la configuración (ver Inicio rápido arriba)
"Acceso denegado" en Windows	Añade `"UV_LINK_MODE": "copy"` al bloque `env` en tu configuración
Errores lentos o repetidos	El servidor reintenta automáticamente: espera un momento e inténtalo de nuevo
Resultados inesperados	Comprueba si hay una versión más reciente: la API de Hardcover puede haber cambiado

Descargo de responsabilidad

Proyecto no oficial. No afiliado con Hardcover.