Project Gutenberg MCP

project-gutenberg-mcp

一个用于阅读 Project Gutenberg 图书的 MCP 服务。

Project Gutenberg 服务条款

Project Gutenberg 的机器人访问政策规定，该网站仅供人类用户使用。自动访问可能导致你的 IP 被封禁。

要使用此 MCP 服务，你必须运行自己的镜像站。Project Gutenberg 明确支持并鼓励建立镜像站——详情请参阅其镜像站指南。

此仓库在 mirror/ 目录中包含一个可直接运行的镜像服务。

镜像站设置

镜像服务会在启动时下载 Project Gutenberg 目录（压缩后约 5 MB），并在首次访问时将图书文件缓存到本地。它提供了此 MCP 服务所需的 URL 结构。

Docker Compose（推荐）

同时运行镜像服务和 MCP 服务。MCP 服务通过 HTTP 暴露在端口 8081。

docker compose up

镜像服务位于 http://localhost:8080，MCP 服务位于 http://localhost:8081/mcp。

仅运行镜像服务（stdio）

构建并启动镜像服务，然后通过 stdio 连接 MCP 客户端。

task build:mirror
task start:mirror

镜像服务运行在 http://localhost:8080。MCP 客户端配置示例（stdio）：

{
  "mcpServers": {
    "project-gutenberg-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GUTENBERG_BASE_URL=http://host.docker.internal:8080",
        "-e", "GUTENBERG_TOOLS=search_books,get_book_metadata,list_passages,get_passage",
        "roberthouse224/project-gutenberg-mcp"
      ]
    }
  }
}

配置

所有配置均通过环境变量完成。

变量	必需	说明
GUTENBERG_BASE_URL	是	你的 Gutenberg 镜像站的基础 URL（见上文“镜像站设置”）
GUTENBERG_TOOLS	是	要公开的工具列表，以逗号分隔（见下文）
GUTENBERG_BOOK_ID	否	用作默认值的 Project Gutenberg 图书 ID
GUTENBERG_CHUNK_SIZE	否	段落大小（字节，默认值：4096）
GUTENBERG_LANGUAGE	否	search_books 的默认 ISO 639-1 语言代码（默认值：en）

工具

工具	说明
search_books	按书名或作者搜索图书
get_book_metadata	获取图书元数据（书名、作者、格式）
fetch_book_text	下载图书的完整纯文本
list_passages	列出图书的固定大小段落键
get_passage	按键获取指定段落

设置 GUTENBERG_BOOK_ID 后，需要图书 ID 的工具会将其用作默认值。如果未设置，请在工具列表中加入 search_books，以便 Agent 先查找 ID。

运行

stdio

GUTENBERG_BASE_URL=http://localhost:8080 \
GUTENBERG_BOOK_ID=2680 \
GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \
./project-gutenberg-mcp --transport stdio

HTTP

GUTENBERG_BASE_URL=http://localhost:8080 \
GUTENBERG_BOOK_ID=2680 \
GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \
./project-gutenberg-mcp --transport http --addr :8081

Docker

拉取预构建镜像

# MCP server
docker pull roberthouse224/project-gutenberg-mcp:1.2.0

# Mirror
docker pull roberthouse224/gutenberg-mirror:1.2.0

在本地构建

两个 Dockerfile 均使用 Docker Hardened Images (DHI) 来增强安全性。构建需要通过 Docker Hub 身份验证：

docker login

然后进行构建：

# Build MCP server
docker build -t project-gutenberg-mcp .

# Build mirror
docker build -f mirror/Dockerfile -t gutenberg-mirror ./mirror

运行 MCP 服务

# HTTP
docker run -p 8081:8081 \
  -e GUTENBERG_BASE_URL=http://host.docker.internal:8080 \
  -e GUTENBERG_BOOK_ID=2680 \
  -e GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \
  roberthouse224/project-gutenberg-mcp --transport http --addr :8081

# stdio
docker run -i --rm \
  -e GUTENBERG_BASE_URL=http://host.docker.internal:8080 \
  -e GUTENBERG_BOOK_ID=2680 \
  -e GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \
  roberthouse224/project-gutenberg-mcp

运行镜像服务

# Create a named volume for cache persistence
docker volume create gutenberg-cache

# Run mirror (serves on http://localhost:8080)
docker run -d \
  -p 8080:8080 \
  -v gutenberg-cache:/data \
  --name gutenberg-mirror \
  roberthouse224/gutenberg-mirror:1.2.0

多架构构建

两个镜像均支持 linux/amd64 和 linux/arm64 架构。要构建并推送多架构镜像：

# Create a builder instance
docker buildx create --name multiarch --use

# Build and push MCP server
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t roberthouse224/project-gutenberg-mcp:1.2.0 \
  -t roberthouse224/project-gutenberg-mcp:latest \
  --push \
  .

# Build and push mirror
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t roberthouse224/gutenberg-mirror:1.2.0 \
  -t roberthouse224/gutenberg-mirror:latest \
  --push \
  -f mirror/Dockerfile \
  ./mirror

MCP 客户端配置（stdio）

{
  "mcpServers": {
    "project-gutenberg-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GUTENBERG_BASE_URL=http://host.docker.internal:8080",
        "-e", "GUTENBERG_BOOK_ID=2680",
        "-e", "GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage",
        "roberthouse224/project-gutenberg-mcp:1.2.0"
      ]
    }
  }
}

本地构建（非 Docker）

task build         # outputs to build/project-gutenberg-mcp
task build:mirror  # outputs to mirror/build/mirror
task test

图书 ID

一些实用的 ID：

图书	ID
沉思录 — 马可·奥勒留	2680
理想国 — 柏拉图	1497
查拉图斯特拉如是说 — 尼采	1998
白鲸 — 梅尔维尔	2701
傲慢与偏见 — 奥斯汀	1342