hardcover-mcp

⚠️ Beta v0.1.0 — 초기 릴리스입니다. API 표면, 도구 이름, 쿼리 구조는 변경될 수 있습니다. 문제 및 피드백은 GitHub Issues를 통해 보고해 주세요.

Hardcover API — 웹사이트, iOS, Android 앱에서 동일한 GraphQL API를 사용하는 도서 추적 플랫폼 — 를 위한 Model Context Protocol (MCP) 서버입니다.

MCP와 호환되는 모든 AI 어시스턴트(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

• Hardcover API 키 — https://github.com/astral-sh/uv/tree/main/installation-and -operations

설치:

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

토큰을 안전하게 보호하세요. Personal Access Token은 당신의 Hardcover 계정에 접근할 수 있습니다. Never commit 전에 버전 관리에 커밋하지 말고 공개적으로 공유하지 마세요. 클라이언트 측 코드에 포함하지 마세요.

사용

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를 통해 가상 환경에 설치한 경우:

{
  "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_API_KEY 설정과 함께 클라이언트를 hardcover-mcp 진입점(또는 python -m hardcover.server)으로 지정하세요. 서버는 stdio를 통해 통신하며 모든 MCP 1.0+ 클라이언트와 호환됩니다.

비율 제한 및 API 정책

이 서버로 도구를 개발하기 전에 읽어 보세요. Hardcover API는 무료이지만 명확한 제한을 갖고 있습니다. 제한을 때 우회적으로 충돌하면 워크플로가 중단될 수 있습니다.

일일 할당량

• 일일 한도: 강력한 상한선입니다. 제한(限)에 도달하면 자정(UTC)까지 모든 요청이 429를 반환합니다.

• 버스트 한도: 조절(throttling) 전에 연속으로 요청할 수 있는 횟수입니다. 분당 요구량에 맞춰 지속적으로 채워지지 않습니다.

• 분당 한도: 모든 요금제는 분당 60회 요청(토큰 버킷)입니다.

• 요청당 리미트: 단일 GraphQL 요청에는 최대 5개의 최상위 레벨 쿼리를 포함할 수 있습니다. 초과하면 429가 아니라 403을 반환합니다.

• 개인 액세스 토큰: 동일한 요금제의 기존 JWT 인증과 비교하여 버스트 용량이 두 배입니다.

이 MCP 서버는 429 반환될 때 retry_after 힌트를 제공하므로, AI 어시스턴트가 원활하게 대기할 수 있습니다.

상업적 이용

Hardcover의 API 정책에 따르면:

• 사용자 소유 데이터(라이브러리, 평점, 리뷰, 독서 일지, 목록, 목표)는 명시적으로 액세스 권한을 부여받은 사용자를 대신하지 않는 한 상업 제품에 사용할 수 없습니다.

• 집계되고 익명화된 데이터(예: Hardcover 독자 수, Hardcover 평균 평점)는 Hardcover로 출처를 확인해 명시하면 상업적으로 사용할 수 있습니다.

• Hardcover에서 제공되는 이미지는 사용자가 업로드한 것입니다. 공개 전시가 되는 경우 DMCA 삭제 요청 정책을 갖춰야 합니다.

금지된 쿼리 패턴

다음 GraphQL 연산자는 API에서 비활성화되어 있습니다:

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

서버 측 쿼리 실행 요구

Hardcover API를 브라우저에서 호출할 수 없습니다. API 키는 안전한 서버 환경에서 유지해야 합니다.

자세한 내용은 공식 Getting Started Guide를 참조하세요.

고지

Hmm wait, I noticed I made some errors in my final answer: I wrote "- 서포터 ... 15 req" - source says 15. OK.

But I also earlier in the final answer, I wrote "| 무료 | 5,000 req/day | 10 req | 60 req/min |" — hmm, in the visible prompt I had "5,000 req/day" for Free and "50,000" for Supporter. Good.

But I need to avoid mixing "없지" etc. In the final answer I mistakenly wrote "연속으로 요청할 수 있는 요청은..." and "충전됩니다" etc. I'll refine these bullets:

• 버스트 한도: 버스트 한도는 정체가 발생하기 전에 연속으로 보낼 수 있는 hầu hết request의 수입니다. 이 한도는 분당 비율로 지속적으로 보충됩니다.

Wait I wrote "빛나게..." No, final answer should be polished.

Also in the "개인 액세스 토큰" bullet: "Personal Access Tokens get double capacity vs legacy JWT auth on the same plan." I wrote "각각의 요금제의..." OK.

But "일일 한도: 하드 캡 ..." good.

Let me also check the "Public instance" bullet words.

Now also "queries must server costs" etc.

Let me carefully finalize the answer without sneaky errors like the wrong "상태: —" or "문자 instance".

Also I must fix "queries: fillable" and typos: "포함됩니다" vs "포함되며". I'll write carefully.

Let me now compose the final exact Korean text in one go.

Also I must preserve the "market" headers "id", "same registers". In the description of get_user_book, I wrote "세션 session" - should be "세션" once; original "read sessions" plural.

Anyway, let me issue final answer properly. To avoid token waste, I'll write the final manually now. Ensure all GXP tokens okay. Also "Configuration" heading "## 설정".

Also one caution: the user message text we need includes "* Disclaimer" and trailing "## Disclaimer" — yes.

Double-check "Commercial Use" bullet 3: "if you디스플레이 them publicly, you must have a DMCA takedown policy" — I need to include the link DMCA takedown policy.

Let me write final now with coherent sentences# hardcover-mcp

⚠️ Beta v0.1.0 — 초기 릴리스입니다. API 표면, 도구 이름, 쿼리 구조는 변경될 수 있습니다. 문제 및 피드백은 GitHub Issues를 통해 보고해 주세요.

Hardcover API — 웹사이트, iOS, Android 앱에서 동일한 GraphQL API를 사용하는 도서 추적 플랫폼 — 를 위한 Model Context Protocol (MCP) 서버입니다.

MCP 호환 AI 어시스턴트(Claude Desktop, Cursor, Kiro 또는 모든 MCP 클라이언트)를 나의 Hardcover 라이브러리, 독서 기록, 목표, Hardcover 전체 도서 카탈로그에 직접 연결하세요.

목차

• 기능

• 도구 참조

• 요구 사항

• 설치

• 설정

• 사용법

  • Claude Desktop

  • Kiro CLI

  • 기타 MCP 클라이언트

• 속도 제한 및 API 정책

• 고지 사항

• 개발

• 기여

• 라이선스

주요 기능

• 🔍 검색 — 도서, 저자, 시리즈, 사용자, 목록, 등장인물, 출판사, 프롬프트 검색

• 📚 라이브러리 탐색 — 모든 상태, 필터링된 뷰, 페이지네이션 결과

• 📖 독서 진행 상황 — 페이지 단위 진행률이 있는 현재 읽고 있는 도서

• 📊 독서 통계 — 이번 달, 올해, 전체 기간 읽은 도서 수와 평균 평점

• 🎯 독서 목표 — 진행률, 상태, 목표치

• 🗓️ 기간별 도서 목록 — 두 날짜 사이에 끝낸 모든 도서 목록

• 📓 독서 일기 — 도서별 세션 이력

• 👤 사용자 프로필 — 본인 프로필과 사용자명으로 조회하는 공개 프로필

• 📋 목록 — 모든 Hardcover 목록과 담긴 도서 조회

• 🏃 활동 피드 — 최근 활동 및 특정 도서에서의 활동

• 🔖 에디션 — 제목, ID 또는 ISBN-10/13으로 검색

• ✍️ 작가 — 프로필 및 저서 목록

• 📖 시리즈 — 정렬·중복이 제거된 도서 목록

도구 참조

사용자 정보

검색

도서

저자

시리즈

내 서재

상태 ID: 1 읽고 싶음 · 2 읽는 중 · 3 다 읽음 · 4 일시 정지 · 5 끝내지 못함 · 6 무시

독서 통계

목표

활동

다른 사용자

목록

요구 사항

• Python 3.10 이상

• uv (권장) 또는 pip

• Hardcover API — 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 key를 추가하세요:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

토큰을 안전하게 보호하세요. Personal Access Token은 책의 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을 가상 환경에 설치했을 경우:

{
  "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_API_KEY 환경 변수를 설정한 상태에서 클라이언트를 hardcover-mcp 엔트리포인트(또는 python -m hardcover.server)로 지정하세요. 서버는 stdio를 통해 통신하며 모든 MCP 1.0+ 클라이언트와 호환됩니다.

비율 제한 및 API 정책

이 서버로 개발하기 전에 꼭 읽어 주세요. Hardcover API는 무료이지만 제한이 분명합니다. 예상치 못하게 제한에 걸리면 작업 흐름이 중단될 수 있습니다.

비율 제한

• 일일 상한: 완전 한도 초과 시 자정(UTC)까지 모든 요청이 429을 반환합니다.

• 버스트 제한: 한 번에 연속해서 보낼 수 있는 요청 수 그 후 스로틀링이 적용됩니다. 분당 요청 수의 속도로 지속적으로 재충전됩니다.

• 분당 제한: 모든 요금제에서 60 요청/분(토큰 버킷).

• 요청당 제한: GraphQL 요청 하나에는 최대 5개의 최상위 쿼리만 포함할 수 있습니다. 이를 초과하면 403이 반환되지가 아니라 429`이 반환됩니다.

• 개인 액세스 토큰: 동일 요금제에서 기존 JWT 인증(legacy JWT)보다 두 배의 버스트 용량이 제공됩니다.

이 MCP 서버는 429가 반환될 때 retry_after 힌트를 제공하므로 AI 어시스턴스가 스무되게 대기할 수 있습니다.

상업적 사용

Hardcover의 API 정책에 따르면:

• 사용자가 소유한 데이터(서재, 평점, 리보, 독서기록, 읽기 세션, 목록, 목표)는 사용자가 명시적으로 허가하지 않는 한 상업 제품에 사용할 수 없습니다.

• 통합된 비표시 데이터(예: Hardcover 독자 수, 동일 평균 평점)는 출처를 표시하면 상업적으로 사용할 수 있습니다.

• Hardcover가 제공하는 이미지는 사용자가 업로드한 것입니다. 공개적으로 표시할 경우 반드시 DMCA 삭제 정책을 갖추어야 합니다.

금지된 쿼리 패턴

API에서 다음 GraphQL 연산자는 비활성화 되어 있습니다:

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

쿼리는 서버 측에서 실행해야 합니다

Hardcover API는 브라우저에서 호출할 수 없습니다 API키는 서버 환경안전 공간에 보관해야 합니다.

자세한 내용은 공식 시작 가이드를 참고하세요.

고지 사항

이 훗은 커뮤니티 기반의 비공식 서버입니다. 본 API와 관련된 부분은 이 절에 명시된 조건에 따라 배포되며, 원하는대로 활요할 수 있습니다. 가능한 한 완성도를 높이려고 하였지만, API 변경 등에 따라 일부 구간이 동작이 다를 수 있습니다. 사용 중 발생하는 문제에 대해 사용자는 지원 및 이유 없이 변경될 수 있는 사항에 대해 인지하고 있어야 합니다.

알림: 이 서버를 사용하면서 발생하는 사항에 대해 어떠한 보증(보증)도 제공하지 않습니다. 응용 프로그램 사용 시 책임은 사용자에게 있습니다. 질문이나 문제를 통해 개선에 참여해 주세요.

이것은 베타 릴리스(v0.1.0)입니다. 이 소프트웨어는 독립적이고 커뮤니티 기반으로 제작된 소프트웨어로, Hardcover와의 제휴, 보증, 또는 지원을 받지 않는 소프트웨어입니다.

• Hardcover API 자체는 베타 단계이며, 호환성을 깨뜨리는 변경(breaking changes)이 적용될 수 있습니다.

• 이 MCP 서버의 도구 이름, 쿼리 구조, 응답 형태는 버전 간에 변경될 수 있습니다.

• 프로덕션 또는 상업적 환경에서의 사용은 전적으로 사용자 본인의 책임입니다.

• 이 서버를 통해 Hardcover API를 사용함으로써 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를 참조하세요.