hardcover-mcp

⚠️ Бета v0.1.0 — Это ранний релиз. API-поверхность, названия инструментов и структура запросов могут измениться. Сообщайте о проблемах и оставляйте отзывы через GitHub Issues.

Сервер Model Context Protocol (MCP) для Hardcover API — платформы для отслеживания книг, которая использует тот же GraphQL API для своего веб-сайта, а также iOS- и Android-приложений.

Подключайте любого MCP-совместимого ИИ-ассистента (Claude Desktop, Cursor, Kiro или любой другой MCP-клиент) напрямую к вашей библиотеке Hardcover, истории чтения, целям и полному каталогу Hardcover.

Содержание

• Возможности

• Справочник инструментов

• Требования

• Установка

• Конфигурация

• Использование

  • Claude Desktop

  • Kiro CLI

  • Другие MCP-клиенты

• Лимиты и политика API

• Отказ от ответственности

• Разработка

• Участие в проекте

• Лицензия

Related MCP server: hardcover-mcp

Возможности

• 🔍 Поиск книг, авторов, серий, пользователей, списков, персонажей, издательств и промптов

• 📚 Просмотр вашей библиотеки — все статусы, отфильтрованные представления и постраничная навигация

• 📖 Прогресс чтения — книги, которые вы читаете сейчас, с прогрессом по страницам

• 📊 Статистика чтения — книги, прочитанные за этот месяц, за этот год и за всё время, со средними оценками

• 🎯 Цели чтения — прогресс, статус и целевое значение для всех ваших целей

• 🗓️ Книги по диапазону дат — список всех книг, прочитанных между двумя датами

• 📓 Журнал чтения — история сессий по каждой книге

• 👤 Профили пользователей — ваш профиль и публичные профили по имени пользователя

• 📋 Списки — получение любого списка Hardcover с его книгами

• 🏃 Лента активности — ваша недавняя активность и активность по конкретным книгам

• 🔖 Издания — поиск по названию, ID или ISBN-10/13

• ✍️ Авторы — профили и библиография

• 📖 Серии — упорядоченные, дедуплицированные списки книг

Справочник инструментов

Идентификация

Поиск

Книги

Авторы

Серии

Моя библиотека

ID статусов: 1 Хочу прочитать · 2 Читаю сейчас · 3 Прочитано · 4 Остановлено · 5 Не дочитал · 6 Игнорировать

Статистика чтения

Цели

Активность

Другие пользователи

Списки

Требования

• Python 3.10 или новее

• uv (рекомендуется) или pip

• Ключ API Hardcover — получите его на hardcover.app/account/api

Установка

С помощью uv (рекомендуется)

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

С помощью pip

git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp
pip install -e .

Из PyPI (когда будет опубликовано)

uv pip install hardcover-mcp
# or
pip install hardcover-mcp

Конфигурация

Скопируйте .env.example в .env и добавьте ключ API:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

Храните токен в секрете. Ваш персональный токен доступа имеет доступ к вашему аккаунту Hardcover. Никогда не коммитьте его в систему контроля версий, не передавайте публично и не встраивайте его в клиентский код.

Использование

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %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"
      }
    }
  }
}

Либо, если установлено через pip/uv в virtualenv:

{
  "mcpServers": {
    "hardcover": {
      "command": "/path/to/venv/bin/hardcover-mcp",
      "env": {
        "HARDCOVER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Kiro CLI

Добавьте в ~/.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": []
    }
  }
}

Другие MCP-клиенты

Укажите в вашем клиенте точку входа hardcover-mcp (или python -m hardcover.server) и задайте для окружения HARDCOVER_API_KEY. Сервер общается через stdio и совместим с любым MCP-клиентом версии 1.0+.

Лимиты и политика API

Прочитайте перед использованием сервера. API Hardcover бесплатен, но имеет строгие лимиты. Их превышение может прервать ваш рабочий процесс.

Лимиты

• Дневной лимит — жёсткий. После его исчерпания все запросы возвращают 429 до полуночи UTC.

• Безпакетный лимит — столько запросов можно выполнить подряд до применения ограничений. Непрерывно пополняется на скорость в минуту.

• Лимит в минуту — 60 запросов в минуту для всех планов (token bucket).

• Лимит на запрос — один GraphQL-запрос может содержать не более 5 запросов верхнего уровня. Превышение онда возвращает 403, а не 429.

• Personal Access Tokens имеют двойной пакетный бонус к лимиту по сравнению с старой JWT-авторизацией на том же плане.

Этот MCP-сервер возвращает подсказки retry_after при получении 429, чтобы ваш ИИ-ассистент мог корректно снизить нагрузку.

Коммерческое использование

Согласно официальных политик API Hardcover:

• Данные пользователя (библиотеки, оценки, рецензии, записи журнала, списки, цели) не могут использоваться в коммерческих продуктах, если вы не действуете от имени пользователя, явно предоставившего доступ.

• Совокупные и обезличенные данные (например, количество читателей Hardcover, средняя оценка Hardcover) могут использоваться при указании на Hardcover как источник данных.

• Изображения от Hardcover загружаются пользователями. Если вы публикуете эти изображения, у вас обязательно должна быть политика удаления по DMCA.

Запрещённые шаблоны запросов

Следующие операторы GraphQL отключены в API:

_like, _nlike, _ilike, _niregex, _nregex, _iregex, _regex, _nsimilar, _similar

Запросы должны выполняться только на сервере

API Hardcover нельзя вызывать из браузера. Ваш ключ API должен хранить в защищённом серверном окружении.

Подробнее в официальном руководстве Getting Started.

Отказ от ответственности

Это бета-релиз (v0.1.0). Это независимое программное обеспечение, созданное сообществом, и оно не связано с Hardcover, не одобрено и не поддерживается Hardcover.

• Сам API Hardcover находится в бете и может претерпевать критические изменения.

• Имена инструментов, структура запросов и формы ответов в этом MCP-сервере могут меняться между версиями.

• Использование в продакшене или в коммерческих целях осуществляется полностью на ваш страх и риск.

• Используя API Hardcover через этот сервер, вы соглашаетесь с правилами Hardcover.

Разработка

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

Структура проекта

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

Запуск тестов

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

Вклад в проект

Вклад приветствуется. Пожалуйста:

1. Сначала откройте issue, чтобы обсудить значимые изменения.

2. Следуйте существующему стилю кода.

3. Добавляйте или обновляйте тесты при изменении поведения.

4. Держите PR сфокусированными — одна функция или одно исправление в каждом PR.

Лицензия

MIT — подробности см. в LICENSE.