hardcover-mcp
Hardcover-MCP
⚠️ Beta v0.1.0 — Esta es una versión preliminar. La superficie de la API, los nombres de las herramientas y la estructura de las consultas pueden cambiar. Informa de errores y cualquier comentario a través de GitHub Issues.
Un servidor de Model Context Protocol (MCP) para la API de Hardcover — la plataforma de seguimiento de libros que usa la misma API GraphQL para su sitio web, iOS y Android.
Conecta cualquier asistente de IA compatible con MCP (Claude Desktop, Cursor, Kiro o cualquier cliente MCP) directamente con tu biblioteca de Hardcover, tu historial de lectura, tus objetivos y el catálogo completo de libros de Hardcover.
Contenido
Related MCP server: hardcover-mcp
Características
🔍 Buscar libros, autores, series, usuarios, listas, personajes, editoriales y prompts
📚 Explora tu biblioteca — todos los estados, vistas filtradas y resultados paginados
📖 Avance de lectura — libros que estás leyendo ahora con progreso página a página
📊 Estadísticas de lectura — libros leídos este mes, este año, todos, con valoraciones medias
🎯 Objetivos de lectura — progreso, estado y meta de todos tus objetivos
🗓️ Libros por intervalo de fechas — lista todos los libros que terminaste entre dos fechas
📓 Diario de lectura — historial de sesiones por libro
👤 Perfiles de usuario — tu perfil y los perfiles públicos por nombre de usuario
📋 Listas — recupera cualquier lista de Hardcover y sus libros
🏃 Feed de actividad — tu actividad reciente y la actividad en libros concretos
🔖 Ediciones — busca por título, ID o ISBN-10/13
✍️ Autores — perfiles y bibliografía
📖 Series — listas de libros ordenadas y deduplicadas
Referencia de herramientas
Identidad
Herramienta | Descripción |
| Perfil del usuario autenticado: id, nombre de usuario, nombre, biografía, ubicación, número de libros, seguidores, insignia, estado Pro |
Búsqueda
Herramienta | Argumentos | Descripción |
|
| Busca libros, autores, series, usuarios, listas, personajes, editoriales o prompts |
Libros
Herramienta | Argumentos | Descripción |
|
| Detalles completos del libro por ID de Hardcover |
|
| Detalles completos del libro mediante el slug de URL (p. ej. |
|
| Todas las ediciones que coinciden exactamente con un título |
|
| Detalles de una sola edición |
|
| Busca una edición por ISBN-10 o ISBN-13 (dñ solo dígitos) |
Autores
Herramienta | Argumentos | Descripción |
|
| perfil del autor por ID |
|
| Autor por slug (p. ej. |
|
| Libros por autor, ordenados por popularidad |
Series
Herramienta | Argumentos | Descripción |
|
| Metadatos de la serie: nombre, descripción, recuento de libros |
|
| Listado de libros ordenado y deduplicado; excluye libros parciales y recopilatorios |
Mi biblioteca
Herramienta | Argumentos | Descripción |
|
| Biblioteca completa, todos los estados, con paginación |
|
| Biblioteca filtrada por estado de lectura |
| — | Libros que se están leyendo actualmente con progreso página a página |
|
| Tu relación con un libro: estado, valoración, reseña, sesiones |
|
| Diario de lectura e historial de sesiones de un libro |
IDs de estado: 1 Quiero leer · 2 Estoy leyendo · 3 Leído · 4 En pausa · 5 No terminado · 6 Ignorado
Estadísticas de lectura
Herramienta | Argumentos | Descripción |
|
| Conteo total + valoración media, y conteo filtrado desde una fecha ( |
|
| Libros terminados entre dos fechas, del más reciente al más antiguo |
Objetivos
Herramienta | Argumentos | Descripción |
| — | Todos los objetivos de lectura con progreso, meta, estado y fechas |
Actividades
Herramienta | Argumentos | Descripción |
|
| Tu feed de actividad (libros añadidos, valorados, res iñados, objetivos, listas) |
|
| Actividad de la comunidad en un libro específico |
Otros usuarios
Herramienta | Argumentos | Descripción |
|
| Busca un perfil público de usuario |
|
| La biblioteca de otro usuario filtrada por estado de lectura |
Listas
Herramienta | Argumentos | Descripción |
|
| Detalles de llista y sus libros (hasta 50) |
Requisitos
Python 3.10 o posterior
uv (recomendado) o pip
Una clave de API de Hardcover — consigue la tuya en hardcover.app/account/api
Instalación
Con uv (recomendado)
git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp
uv syncCon pip
git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp
pip install -e .Desde PyPI (cuando esté publicado)
uv pip install hardcover-mcp
# or
pip install hardcover-mcpConfiguración
Copia .env.example a .env y añade tu clave de API:
cp .env.example .envHARDCOVER_API_KEY=your_api_key_hereMantén tu token en privado. Tu token de acceso personal tiene acceso a tu cuenta de Hardcover. Nunca lo incluyas en control de version, lo compartas públicamente o lo incorporas en código de cliente.
Uso
Claude Desktop
Añade la siguiente configuración en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"hardcover": {
"command": "uv",
"args": [
"run",
"--with-editable",
"/path/to/hardcover-mcp",
"hardcover-mcp"
],
"env": {
"HARDCOVER_API_KEY": "your_api_key_here"
}
}
}
}O si lo instalaste mediante pip/uv dentro de un virtualenv:
{
"mcpServers": {
"hardcover": {
"command": "/path/to/venv/bin/hardcover-mcp",
"env": {
"HARDCOVER_API_KEY": "your_api_key_here"
}
}
}
}Kiro CLI
Añade a ~/.kiro/settings/mcp.json:
{
"mcpServers": {
"hardcover": {
"command": "/path/to/uv",
"args": [
"run",
"--with-editable",
"/path/to/hardcover-mcp",
"hardcover-mcp"
],
"env": {
"HARDCOVER_API_KEY": "your_api_key_here"
},
"disabled": false,
"autoApprove": []
}
}
}Otros clientes MCP
Apunta tu cliente al punto de entrada hardcover-mcp (o python -m hardcover.server) con la variable HARDCOVER_API_KEY definida en el entorno. El servidor se comunica a través de stdio y es compatible con cualquier cliente MCP 1.0 o superior.
Límites de uso y política API
Lee esto antes de crear tu proyecto con este servidor. La API de Hardcover es de uso gratuito, pero tiene límites estrictos. Si puedes alcanzarlos sin esperarlo, esto podría interrumpir tu flujo de trabajo.
Límites de solicitudes
Plan | Diarias | Ráfaga | Por minuto |
Free | 5.000 peticiones/día | 10 peticiones | 60 peticiones/min |
Supporter | 50.000 peticiones/día | 15 peticiones | 60 peticiones/min |
Límite diario: tope máximo. Si lo alcanzas, todas las solicitudes retornarán
429hasta la medianoche UTC.Límite de ráfaga: cuántas solicitudes puedes lanzar consecutivamente antes de que se aplique cifrado. Se rellena de forma continua según la frecuencia por minuto.
Límite por minuto: 60 pet/min para todos los planes (bucket simbólico).
Límite por solicitud: una sola petición GraphQL puede tener como máximo 5 consultas de nivel superior. Sobre esto devuelve
403, no429.Tokens de acceso personales tienen una ráfaga doble respecto al método heredado JWT en el mismo plan.
Este servidor MCP contribuye con la sugerencia when retry_after si se devuelve un 429, para que tu asistente de IA pueda espera con gracia.
Uso comercial
Según la política API de Hardcover:
Datos propios del usuario (bibliotecas, valoraciones, reseñas, entradas diario, listas, objetivos) no pueden usarse en productos comerciales excepto cuando actúes en representación de un usuario que te haya concedido acceso expresamente.
one: datos agregados y anónimos (p. ej., número de leectores de Hardcover, valoración media en Hardcover) pueden usarse comercialmente si se cita a Hardcover.
Las imágenes servidas desde Hardcover son subidas por los usuarios. Si las muestras de forma pública, debes tener una política de retirada DMCA.
Patrones de consulta prohibidos
Los siguientes operadores GraphQL están desactivados en la API:
_like, _nlike, _ilike, _niregex, _nregex, _iregex, _regex, _nsimilar, _similar
Las consultas deben ejecutarse en el servidor
No se puede llamar a la API de Hardcover desde un navegador. Tu clave de API debe guardarse en un entorno servidor seguro.
Para más información, consulta la guía oficial para empezar.
Descargo de responsabilidad
Esta es una versión beta (v0.1.0). Es una versión beta independiente, creada por la comunidad, y no está afiliada, respaldada ni soportada por Hardcover.
La API de Hardcover está en fase beta y sujeta a cambios que pueden romper la compatibilidad.
Los nombres de las herramientas, la estructura de las consultas y la forma de las respuestas en este servidor MCP pueden cambiar entre versiones.
El uso en entornos de producción o contextos comerciales es totalmente bajo tu propio riesgo.
Al usar la API de Hardcover a través de este servidor, aceptas las políticas de Hardcover.
Desarrollo
git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp
# Create virtualenv and install with dev deps
uv sync --extra dev
# or: pip install -e ".[dev]"
# Run tests
uv run pytest
# or: python -m pytest
# Run the server locally (needs HARDCOVER_API_KEY in environment)
HARDCOVER_API_KEY=your_key hardcover-mcpEstructura del proyecto
hardcover-mcp/
├── hardcover/
│ ├── __init__.py
│ ├── client.py # GraphQL HTTP client, rate-limit handling, error mapping
│ ├── queries.py # All GraphQL query strings
│ └── server.py # MCP server, tool definitions, dispatch
├── tests/
│ ├── conftest.py # Shared fixtures
│ ├── test_client.py # 30 client tests (HTTP errors, rate limits, response parsing)
│ └── test_server.py # 51 server tests (tool dispatch, error formatting)
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.mdEjecutar pruebas
pytest # all tests
pytest tests/test_client.py # client only
pytest tests/test_server.py # server only
pytest -v # verboseContribuciones
Las contribuciones son bienvenidas. Por favor:
Abre un issue primero para discutir los cambios significativos
Sigue el estilo de código existente
Añade o actualiza las pruebas para cualquier cambio de comportamiento
Mantén las PR enfocadas — una funcionalidad o corrección por PR
Licencia
MIT — consulta LICENSE para obtener detalles.
Available Tools
25 toolsget_author_booksA
Get books written by a specific author, ordered by popularity.
Inputs: author_id (required), limit, offset.
get_author_by_idA
Get an author's profile by Hardcover author ID.
Inputs: id (required).
get_author_by_slugA
Get an author's profile by URL slug (e.g. 'brandon-sanderson').
Inputs: slug (required).
get_book_activitiesA
Get recent user activity for a specific book (ratings, reviews, status changes).
Inputs: book_id (required), limit, offset.
get_book_by_idB
Get full book details by Hardcover book ID.
Inputs: id (required).
get_book_by_slugA
Get full book details by Hardcover URL slug (e.g. 'the-name-of-the-wind').
Inputs: slug (required).
get_books_in_seriesA
Get the ordered, deduplicated list of books in a series. Merges duplicates, excludes partial books and compilations.
Inputs: series_id (required).
get_books_read_betweenA
List books marked as Read with a finish date between two dates, ordered most-recent first.
Inputs: since (required), until (required), user_id (required), limit, +1 more.
get_edition_by_idA
Get detailed information about a specific edition by its ID.
Inputs: id (required).
get_editions_by_isbnB
Look up an edition by ISBN-10 or ISBN-13.
Inputs: isbn (required).
get_editions_by_titleA
Get all known editions of a book by exact title match.
Inputs: title (required).
get_library_by_statusA
Get the authenticated user's books filtered by reading status. Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish, 5=Owned.
Inputs: status_id (required), limit, offset.
get_list_by_idA
Get a Hardcover list's details and its books (up to 50 books).
Inputs: id (required).
get_meA
Get the currently authenticated Hardcover user's profile (id, username, name, book counts).
Inputs: no named parameters.
get_my_activitiesA
Get a user's recent activity feed (books added, rated, reviewed, goals, lists). Requires the user's numeric ID.
Inputs: user_id (required), limit, offset.
get_my_goalsA
Get the authenticated user's reading goals (progress, target, state, dates).
Inputs: no named parameters.
get_my_libraryA
Get the authenticated user's full library (all statuses), paginated.
Inputs: limit, offset.
get_my_reading_journalB
Get reading journal entries and session history for a specific book.
Inputs: book_id (required).
get_reading_progressB
Get all books currently being read with their page-level progress.
Inputs: no named parameters.
get_reading_statsA
Get reading statistics: total books read all-time AND since an optional date (e.g. '2026-01-01' for this year, '2026-08-01' for this month), plus average rating for each window. Requires the user's numeric ID (use get_me to find it).
Inputs: user_id (required), since.
get_series_by_idA
Get series metadata (name, description, book count) by series ID.
Inputs: id (required).
get_user_bookA
Get the authenticated user's relationship with a specific book (status, rating, review, read sessions).
Inputs: book_id (required).
get_user_by_usernameB
Look up a public Hardcover user profile by username.
Inputs: username (required).
get_user_libraryA
Get another user's library filtered by reading status. Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish, 5=Owned.
Inputs: user_id (required), status_id (required), limit, offset.
searchA
Search Hardcover for books, authors, series, users, lists, characters, publishers, or prompts. Returns rich result objects from Typesense. query_type defaults to 'book'.
Inputs: query (required), page, per_page, query_type.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools map cleanly to distinct resources: books, editions, authors, series, users, libraries, progress, stats, and activities. The main minor ambiguities are the parallel id/slug lookups for books/authors and the broad `search` tool, but these are clearly separated by input type.
The overwhelming majority of tools follow a predictable `get_<resource>` or `get_<resource>_by_<key>` snake_case pattern. The single standalone `search` tool is a minor but logical exception, and it does not disrupt the overall consistency.
25 tools is at the boundary where a server starts to feel heavy, though each tool is a distinct read-only lookup in a rich book/reading domain. Some consolidation, especially around edition lookups and library/status variants, could reduce redundancy without losing functionality.
The read-only surface is strong: it covers books, editions, authors, series, users, libraries, reading progress, stats, lists, and activities. However, it offers no create/update/delete capabilities for library status, ratings, reviews, or lists, so users expecting a full reading-app workflow will hit dead ends.
Maintenance
Related MCP Connectors
Read and update your Hardcover library, progress, lists, and goals. Sign in with Hardcover OAuth.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
AI assistant integration for Leaf — track books, log reading sessions, and manage your library.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to help users manage their reading experience by searching books, tracking reading progress, managing bookmarks, and generating personalized recommendations and summaries.-
- AlicenseAqualityBmaintenanceConnects AI assistants to the Hardcover book library, enabling natural language book searches, reading status updates, list management, and library exploration.28143 PyPI10MIT
- AlicenseAqualityBmaintenanceConnects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.19590 npm31MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude, ChatGPT, and other MCP clients to read and manage a Hardcover account's library, reading progress, reviews, journal, lists, goals, follows, and notifications through 53 read/write tools. It is a hosted remote server that connects each user to their own account via Hardcover's OAuth sign-in, with six raw GraphQL tools reaching anything else in the API.3MIT