Hardcover Mcp

hardcover-mcp

通过任何 AI 助手使用你的 Hardcover 书库。

hardcover-mcp 将你的 Hardcover 书库连接到 Claude 和 Copilot 等 AI 助手。搜索书籍、更新阅读状态、管理书单、探索系列——只需自然对话，无需逐个点击菜单。

你可以这样说

“我的正在阅读书单里有哪些书？”

“把《挽救计划》添加到我的书库，并设为正在阅读”

“搜索 Brandon Sanderson 写的书”

“查找 ISBN 9780547928227”

“创建一个名为‘夏日阅读’的书单，并把《霍比特人》添加进去”

“按阅读顺序展示我《飓光志》系列的书籍”

“把《挽救计划》和《火星救援》移至正在阅读”

“Andy Weir 写过哪些书？把我还没读过的书添加到想读书单”

“比较我对《沙丘》的评分和 Hardcover 的平均评分”

支持的功能

• 书库追踪 — 状态、评分、阅读日期
• 书单管理 — 创建、编辑、添加或移除书籍
• 发现 — 搜索书籍、作者、系列、版本等
• 账户信息 — 个人资料和阅读统计

安全与控制

• 由你掌控 API 密钥 — 密钥保留在你的设备上，不会与第三方共享
• 通过 MCP 客户端在本地运行 — 不涉及外部服务
• 仅在明确请求时执行操作 — 不会在后台运行任何操作
• 发送任何内容前，你都可以在客户端中查看提示词和输出
• 只读模式 — 设置 HARDCOVER_READ_ONLY=true，隐藏所有可更改账户的工具（请参阅配置）
• 最小权限密钥 — 仅授予密钥所需的权限范围；只读密钥会让 Hardcover 自行拒绝写入操作（请参阅 API 密钥和权限范围）

快速开始

1. 安装 uv（一个快速的 Python 包运行工具——设置只需几秒钟）。
2. 在 hardcover.app/account/api 创建 API 密钥；有关自动选择正确权限范围的链接，请参阅 API 密钥和权限范围。
3. 将下方配置添加到你的 MCP 客户端——无需手动安装，uvx 会处理一切。

VS Code

添加到 .vscode/mcp.json：

{
  "servers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

Claude Code

claude mcp add --scope user hardcover --env HARDCOVER_API_TOKEN=<your token> -- uvx hardcover-mcp

将 <your token> 替换为你的 Hardcover API 密钥。--scope user 会使服务在每个项目中都可用；省略此参数则只会将其添加到当前项目（有关权限范围，请参阅 Claude Code MCP 文档）。配置中的其他设置可作为额外的 --env KEY=value 标志添加在服务名称之后，例如 --env HARDCOVER_READ_ONLY=true。

若要避免将令牌放在命令行中，请将变量放入文件，并让 uvx 读取：

claude mcp add --scope user hardcover -- uvx --env-file /path/to/hardcover.env hardcover-mcp

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

HARDCOVER_TOOLSETS 和 HARDCOVER_READ_ONLY 是可选项，此处展示的是它们的默认值； 配置列出了所有设置，包括 HARDCOVER_API_URL。

若要避免将令牌放入客户端配置，请将变量放入 .env 文件，并让 uvx 读取该文件。服务只会读取你指定的文件：

"command": "uvx",
"args": ["--env-file", "/path/to/hardcover.env", "hardcover-mcp"]

API 密钥和作用域

Hardcover API 密钥带有作用域，用于限制密钥可执行的操作。创建密钥时，仅授予此服务所需的作用域（以下链接会打开已预选这些作用域的 Hardcover 密钥表单）：

• 全部：创建包含所有作用域的密钥
• 只读：创建只读密钥。将其与 HARDCOVER_READ_ONLY=true 搭配使用；这样即使工具尝试写入，Hardcover 也会拒绝。

工具集	所需作用域
core	read:catalog、read:library、read:me、read:social、read:users
catalog	read:catalog、read:vibes
library	read:catalog、read:goals、read:library、read:lists、read:me、write:goals、write:library、write:reviews
lists	read:lists、read:me、write:lists
journal	read:journal、read:me、write:library
social	read:me、read:prompts、read:social、read:users、write:prompts、write:social

几乎所有工具都需要 read:me，因为工具会先查询你的身份。只有使用 set_user_book 撰写或编辑书评时才需要 write:reviews；没有此作用域，状态、评分和笔记仍可修改。如果你只加载部分工具集（请参阅配置），密钥只需具备对应行中的作用域以及 core 所需的作用域。

• 2026 年 8 月之前创建的密钥拥有完整访问权限，且仍可正常使用。
• 创建密钥时，Hardcover 会要求你设置到期日期。密钥到期后，每个工具都会返回 "Hardcover rejected the API token … expired"，并附上创建新密钥的链接。
• 如果工具需要的作用域不在你的密钥中，错误会指出缺少的作用域，并提供一个已预选这些作用域的密钥表单链接。

配置

可选环境变量，与令牌一起设置在同一个 env 块中：

变量	默认值	作用
HARDCOVER_TOOLSETS	all	要加载的工具集，以逗号分隔。工具越少，所用上下文越少，选错工具的情况也越少。
HARDCOVER_READ_ONLY	false	设为 true 时，隐藏所有会创建、更改或删除内容的工具。
HARDCOVER_API_URL	Hardcover 的 API	要调用的 GraphQL 端点，例如代理。必须使用 https://，因为每个请求都会携带你的令牌。

工具集	涵盖范围
core	始终加载：search_books、get_user
catalog	书籍（含角色和版本）、版本、作者、系列、出版社、热门内容、氛围
library	你的书库、阅读日期和进度、所有权、书评、统计数据、目标
lists	查看和管理你的列表
journal	阅读日志中的笔记和引文
social	动态、关注用户、社区提示词

例如，一个用于浏览书籍和个人书库的只读助手：

"env": {
  "HARDCOVER_API_TOKEN": "<your token>",
  "HARDCOVER_TOOLSETS": "catalog,library",
  "HARDCOVER_READ_ONLY": "true"
}

未知的工具集名称会导致服务在启动时停止，并显示有效名称列表。

工具

按工具集分组（请参阅配置）。标有 ✏️ 的工具可以更改你的帐户，在只读模式下会隐藏。

core（始终加载）

可执行的操作	工具
搜索书籍、作者、系列、列表、用户等（可排序和筛选）	search_books
查看个人资料和阅读统计数据，或查询其他用户；还可选择查看其书库、关注者和关注对象	get_user

目录

可执行的操作	工具
按 ID 或 slug 查找书籍，包括贡献者及其角色（可选包含角色和版本）；或按 ISBN、ASIN 或版本 ID 查找特定版本	get_book
浏览作者的作品目录	get_author
按阅读顺序浏览系列	get_series
查找出版商及其版本	get_publisher
查看当前热门书籍	get_trending_books
浏览精选推荐合集（氛围）	get_vibes

书库

可执行的操作	工具
浏览你的书库：按状态、日期范围、是否已评论或是否拥有进行筛选；按评分／日期排序	get_user_library
查看某本书的状态、评分、评论、阅读记录和所属书单（不包括内部的“已拥有”书单）	get_user_book
获取当前阅读目标及进度	get_reading_goal
✏️ 添加书籍，或更新其状态、评分、评论、笔记、隐私设置、版本和拥有状态	set_user_book
✏️ 记录或编辑阅读日期和进度（页数、有声书时长）	set_user_book_read
✏️ 创建、更新或归档阅读目标（书籍／页数、日期范围）	set_reading_goal
✏️ 删除阅读目标	delete_reading_goal
✏️ 删除阅读记录或整本书	delete_user_book_read / delete_user_book

书单

可执行的操作	工具
查看你的书单，或查看某个书单及其中的书籍	get_list
✏️ 创建或重命名书单，或更改其隐私设置	set_list
✏️ 在一个书单（list_id）或最多 20 个书单（list_ids）中添加或移除书籍	set_list_book
✏️ 删除书单	delete_list

日记

可执行的操作	工具
阅读你的日记条目（笔记、引文、状态事件）	get_reading_journal
✏️ 添加或编辑日记笔记／引文	set_journal_entry
✏️ 删除日记条目	delete_journal_entry

社交

可执行的操作	工具
查看你关注的人（或某个用户）的近期动态	get_activity_feed
✏️ 关注或取消关注用户	set_following
浏览社区书籍提示	get_prompts
✏️ 用一本书回答提示，或撤回回答	set_prompt_answer

开发

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

Lint 和格式检查（使用 Ruff）：

uv run ruff check .
uv run ruff format --check .

运行测试：

uv run pytest tests/ -v

集成测试

集成测试会调用在线 Hardcover API，并需要有效令牌。在 CI 中以及令牌缺失时，测试会自动跳过。

要在本地运行，请在仓库中创建一个 .env 文件并填入你的令牌（测试会加载该文件；服务本身只读取真实环境变量）：

HARDCOVER_API_TOKEN=your_token_here

然后运行：

uv run pytest tests/integration/ -v

写入测试遵循“创建 → 验证 → 删除”的生命周期，因此不会更改账户内容。

贡献

欢迎贡献！请：

1. 先创建议题，讨论拟议的更改。
2. Fork 仓库并创建分支（feature/short-description 或 fix/short-description）。
3. 提交前运行 lint 和测试：

   uv run ruff check .
   uv run ruff format --check .
   uv run pytest tests/ -v
   

4. 让 PR 专注于单一主题——每个 PR 只做一项更改。
5. 使用约定式提交前缀：feat:、fix:、chore:、docs:。

速率限制

Hardcover API 每分钟允许 60 次请求，并允许短暂突发请求；另有每日限额（免费套餐为 5,000 次请求）。服务会将请求排队、遵循 API 的速率限制标头，并在收到等待要求时重试。每次最多等待一分钟；如果 Hardcover 要求等待更久，调用就会停止并告知需要等待多久。达到每日限额后，服务会立即停止并说明原因（限额于 UTC 午夜重置）。你可以在 hardcover.app/account/api 查看用量。2026 年 8 月之后创建的密钥，其突发请求额度是较早创建的密钥的两倍。

故障排查

问题	解决方法
"API token is not set"	将你的 token 添加到配置中（参见上方的快速入门）
"Hardcover rejected the API token"	密钥无效或已过期；使用错误消息中的链接创建新密钥
"missing the scope(s) this tool needs"	创建包含所需权限范围的密钥；错误消息中有一个预填表单的链接
"daily API limit … is used up"	等到 UTC 午夜，或减少加载的工具数量以减少调用次数
"rate limit asks to wait N seconds"	Hardcover 正在限制此密钥的调用频率；等待相应时间后重试
"Hardcover didn't answer within 30 seconds"	请重试；如果你请求了更改，请先检查更改是否已保存
"Access is denied" on Windows	在配置中的 env 块添加 "UV_LINK_MODE": "copy"
运行缓慢或反复报错	服务会自动重试——稍等片刻后重试
结果异常	检查是否有更新版本：Hardcover API 可能已更改

免责声明

非官方项目。与 Hardcover 无关联。