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

• Características

• Referencia de herramientas

• Requisitos

• Instalación

• Configuración

• Cómo usarlo

  • Claude Desktop

  • Kiro CLI

  • Otros clientes MCP

• Límites de uso y política de la API

• Aviso legal

• Desarrollo

• Contribuciones

• Licencia

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

Búsqueda

Libros

Autores

Series

Mi biblioteca

IDs de estado: 1 Quiero leer · 2 Estoy leyendo · 3 Leído · 4 En pausa · 5 No terminado · 6 Ignorado

Estadísticas de lectura

Objetivos

Actividades

Otros usuarios

Listas

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 sync

Con 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-mcp

Configuración

Copia .env.example a .env y añade tu clave de API:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

Manté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

• Límite diario: tope máximo. Si lo alcanzas, todas las solicitudes retornarán 429 hasta 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, no 429.

• 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-mcp

Estructura 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.md

Ejecutar pruebas

pytest                  # all tests
pytest tests/test_client.py   # client only
pytest tests/test_server.py   # server only
pytest -v               # verbose

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Abre un issue primero para discutir los cambios significativos

2. Sigue el estilo de código existente

3. Añade o actualiza las pruebas para cualquier cambio de comportamiento

4. Mantén las PR enfocadas — una funcionalidad o corrección por PR

Licencia

MIT — consulta LICENSE para obtener detalles.