hardcover-mcp

🚀 Hardcover MCP

Hardcover MCP 是一个模型上下文协议（MCP）服务器，它提供对 Hardcover.app GraphQL API 的只读访问。工具按照 books.*、users.* 和 series.* 进行命名空间划分，同时还包含资源和提示，以指导进行安全、小流量的查询。

这是一个非官方的、由社区维护的服务器，与 Hardcover.app 没有关联。

🚀 快速开始

本项目提供对 Hardcover.app GraphQL API 的只读访问，通过特定命名空间工具和资源提示确保查询安全、低流量。

✨ 主要特性

• 提供对 Hardcover.app GraphQL API 的只读访问。
• 工具按 books.*、users.* 和 series.* 命名空间划分。
• 包含资源和提示，指导安全、低流量查询。

📦 安装指南

安装要求

• Python 3.11+
• 从 https://hardcover.app/account/api 获取 Hardcover API 密钥（只读的 Bearer 令牌）

安装步骤

# 选项 A：使用 uv（推荐）
uv pip install -e .

# 选项 B：使用 pip
python -m venv .venv
source .venv/bin/activate
pip install -e .

🔧 技术细节

传输协议

本服务器目前仅支持将 STDIO 作为传输协议。

💻 使用示例

基础用法

1. 获取 API 密钥

从 https://hardcover.app/account/api 获取 API 密钥。精确复制提供的值（它已经以 Bearer 开头）。

2. 为服务器导出密钥

export HARDCOVER_API_KEY="Bearer <your-token>"

3. 直接启动 MCP 服务器

uv run src/hardcover_mcp/main.py

高级用法

为 AI 聊天配置 STDIO（以 Codex 为例）

[mcp_servers.hardcover_mcp]
command = "uv"
args = ["run", "src/hardcover_mcp/main.py"]
env = { "HARDCOVER_API_KEY" = "API KEY heRE" }
cwd = "full_path_to/hardcover_mcp"

服务器会注册 books.*、users.* 和 series.* 工具命名空间，以及 hardcover/tag-categories 等资源和 hardcover/fantasy-this-year 等使用提示。

运行测试套件

pytest

📚 详细文档

故障排除

• HARDCOVER_API_KEY environment variable is required：确保在启动服务器的同一 shell 中设置了该变量，并包含开头的 Bearer 前缀。
• Hardcover API returned an error response 或 401/403：确认令牌有效且未过期。
• 响应缓慢或超时：减少 limit/offset 参数；API 实施了速率限制。从 limit<=10 开始。
• SSL/HTTP 传输问题：检查本地网络/代理设置，并使用稳定的连接重试。