hardcover-mcp

⚠️ Beta v0.1.0 — 这是早期版本。API 接口范围、工具名称和查询结构可能会发生变化。请通过 GitHub Issues 报告问题和反馈。

一个面向 Hardcover API 的 Model Context Protocol (MCP) 服务器。Hardcover 是图书追踪平台，其网站、iOS 和 Android 应用都使用同一个 GraphQL API。

将任何兼容 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 密钥 — 前往 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 安装在虚拟环境中：

{
  "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 政策

在使用本服务器开发前，请务必阅读。 Hardcover API 是免费的，但存在硬性限制。意外触发限制可能会影响你的工作流。

速率限制

• 每日限额：硬性限制。一旦达到，所有请求将返回 429，直到 UTC 午夜。

• 突发限额：限流前可连续发出的请求数量。每分钟动态补充。

• 每分钟限额：所有套餐均为 60 请求/分钟（令牌桶）。

• 单次请求限额：一个 GraphQL 请求最多包含 5 个顶层查询。超出会返回 403 而非 429。

• Personal Access Tokens 在同一套餐下，其突发容量为旧版 JWT 认证的两倍。

该 MCP 服务器会在返回 429 时给出 retry_after 提示，方便 AI 助手从容退出。

商业使用

根据 Hardcover API 政策：

• 用户自有数据（藏书、评分、书评、日志、列表、目标）不得用于商业产品，除非你代表明确授权的用户行动。

• 聚合、匿名化数据（如 Hardcover 读者数量、Hardcover 平均评分）可用于商业用途，但需要注明来源。

• Hemat from Hardcover 的图片为普通用户上传。如果你公开展示，必须提供 DMCA 删除政策。

禁止的查询模式

以下 GraphQL 运算符已被 API 禁用：

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

查询必须在服务端执行

Hardcover API 不得从浏览器调用。API 密钥必须保存在安全的服务器环境中。

更多详情请参阅官方 入门指南。

免责声明

这是一个测试版（v0.1.0）。 它是独立的社区构建软件，不隶属于 Hardcover，也不受其认可或支持。

• Hardcover API 本身也处于 beta 阶段，并可能发生破坏性变更。

• 此 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。