{
  "markdown": "# project-gutenberg-mcp\n\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers/io.github.bobbyhouse%2Fproject-gutenberg-mcp/versions/latest)\n[![Docker Hub](https://img.shields.io/docker/v/roberthouse224/project-gutenberg-mcp?label=Docker+Hub)](https://hub.docker.com/r/roberthouse224/project-gutenberg-mcp)\n\nAn MCP server for reading books from [Project Gutenberg](https://www.gutenberg.org).\n\n## Project Gutenberg Terms of Service\n\nProject Gutenberg's [robot access policy](https://www.gutenberg.org/policy/robot_access.html) states that the site is intended for human users only. Automated access may result in your IP being blocked.\n\nTo use this MCP server you must run your own mirror. Project Gutenberg explicitly supports and encourages mirroring — see their [mirroring guide](https://www.gutenberg.org/help/mirroring.html) for details.\n\nThis repository includes a ready-to-run mirror server in the `mirror/` directory.\n\n## Mirror Setup\n\nThe mirror server downloads the Project Gutenberg catalog on startup (~5 MB compressed) and caches book files locally on first access. It exposes the URL structure that this MCP server expects.\n\n### Docker Compose (recommended)\n\nRuns the mirror and MCP server together. The MCP server is exposed on HTTP at port 8081.\n\n```bash\ndocker compose up\n```\n\nThe mirror is available at `http://localhost:8080` and the MCP server at `http://localhost:8081/mcp`.\n\n### Mirror only (stdio)\n\nBuild and start just the mirror, then connect an MCP client via stdio.\n\n```bash\ntask build:mirror\ntask start:mirror\n```\n\nThe mirror runs at `http://localhost:8080`. Example MCP client config (stdio):\n\n```json\n{\n  \"mcpServers\": {\n    \"project-gutenberg-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"GUTENBERG_BASE_URL=http://host.docker.internal:8080\",\n        \"-e\", \"GUTENBERG_TOOLS=search_books,get_book_metadata,list_passages,get_passage\",\n        \"roberthouse224/project-gutenberg-mcp\"\n      ]\n    }\n  }\n}\n```\n\n## Configuration\n\nAll configuration is via environment variables.\n\n| Variable | Required | Description |\n|---|---|---|\n| `GUTENBERG_BASE_URL` | Yes | Base URL of your Gutenberg mirror (see Mirror Setup above) |\n| `GUTENBERG_TOOLS` | Yes | Comma-separated list of tools to expose (see below) |\n| `GUTENBERG_BOOK_ID` | No | Project Gutenberg book ID to use as default |\n| `GUTENBERG_CHUNK_SIZE` | No | Passage size in bytes (default: 4096) |\n| `GUTENBERG_LANGUAGE` | No | Default ISO 639-1 language code for `search_books` (default: `en`) |\n\n### Tools\n\n| Tool | Description |\n|---|---|\n| `search_books` | Search for books by title or author |\n| `get_book_metadata` | Fetch metadata (title, authors, formats) for a book |\n| `fetch_book_text` | Download the full plain text of a book |\n| `list_passages` | List fixed-size passage keys for a book |\n| `get_passage` | Fetch a specific passage by its key |\n\nWhen `GUTENBERG_BOOK_ID` is set, tools that take a book ID will use it as the default. When it is not set, include `search_books` in your tools list so an agent can discover IDs first.\n\n## Running\n\n### stdio\n\n```bash\nGUTENBERG_BASE_URL=http://localhost:8080 \\\nGUTENBERG_BOOK_ID=2680 \\\nGUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \\\n./project-gutenberg-mcp --transport stdio\n```\n\n### HTTP\n\n```bash\nGUTENBERG_BASE_URL=http://localhost:8080 \\\nGUTENBERG_BOOK_ID=2680 \\\nGUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \\\n./project-gutenberg-mcp --transport http --addr :8081\n```\n\n## Docker\n\n### Pulling pre-built images\n\n```bash\n# MCP server\ndocker pull roberthouse224/project-gutenberg-mcp:1.2.0\n\n# Mirror\ndocker pull roberthouse224/gutenberg-mirror:1.2.0\n```\n\n### Building locally\n\nBoth Dockerfiles use [Docker Hardened Images (DHI)](https://docs.docker.com/dhi/) for enhanced security. Building requires authentication to Docker Hub:\n\n```bash\ndocker login\n```\n\nThen build:\n\n```bash\n# Build MCP server\ndocker build -t project-gutenberg-mcp .\n\n# Build mirror\ndocker build -f mirror/Dockerfile -t gutenberg-mirror ./mirror\n```\n\n### Running the MCP server\n\n```bash\n# HTTP\ndocker run -p 8081:8081 \\\n  -e GUTENBERG_BASE_URL=http://host.docker.internal:8080 \\\n  -e GUTENBERG_BOOK_ID=2680 \\\n  -e GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \\\n  roberthouse224/project-gutenberg-mcp --transport http --addr :8081\n\n# stdio\ndocker run -i --rm \\\n  -e GUTENBERG_BASE_URL=http://host.docker.internal:8080 \\\n  -e GUTENBERG_BOOK_ID=2680 \\\n  -e GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage \\\n  roberthouse224/project-gutenberg-mcp\n```\n\n### Running the mirror\n\n```bash\n# Create a named volume for cache persistence\ndocker volume create gutenberg-cache\n\n# Run mirror (serves on http://localhost:8080)\ndocker run -d \\\n  -p 8080:8080 \\\n  -v gutenberg-cache:/data \\\n  --name gutenberg-mirror \\\n  roberthouse224/gutenberg-mirror:1.2.0\n```\n\n## Multi-architecture builds\n\nBoth images support `linux/amd64` and `linux/arm64` architectures. To build and push multi-arch images:\n\n```bash\n# Create a builder instance\ndocker buildx create --name multiarch --use\n\n# Build and push MCP server\ndocker buildx build \\\n  --platform linux/amd64,linux/arm64 \\\n  -t roberthouse224/project-gutenberg-mcp:1.2.0 \\\n  -t roberthouse224/project-gutenberg-mcp:latest \\\n  --push \\\n  .\n\n# Build and push mirror\ndocker buildx build \\\n  --platform linux/amd64,linux/arm64 \\\n  -t roberthouse224/gutenberg-mirror:1.2.0 \\\n  -t roberthouse224/gutenberg-mirror:latest \\\n  --push \\\n  -f mirror/Dockerfile \\\n  ./mirror\n```\n\n## MCP client config (stdio)\n\n```json\n{\n  \"mcpServers\": {\n    \"project-gutenberg-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"GUTENBERG_BASE_URL=http://host.docker.internal:8080\",\n        \"-e\", \"GUTENBERG_BOOK_ID=2680\",\n        \"-e\", \"GUTENBERG_TOOLS=get_book_metadata,list_passages,get_passage\",\n        \"roberthouse224/project-gutenberg-mcp:1.2.0\"\n      ]\n    }\n  }\n}\n```\n\n## Local builds (non-Docker)\n\n```bash\ntask build         # outputs to build/project-gutenberg-mcp\ntask build:mirror  # outputs to mirror/build/mirror\ntask test\n```\n\n## Book IDs\n\nA few useful IDs:\n\n| Book | ID |\n|---|---|\n| Meditations — Marcus Aurelius | 2680 |\n| The Republic — Plato | 1497 |\n| Thus Spoke Zarathustra — Nietzsche | 1998 |\n| Moby Dick — Melville | 2701 |\n| Pride and Prejudice — Austen | 1342 |\n",
  "bytes": 6408,
  "sha": "e802f91d7e334e98e2179818d11746ac23ab8b50abec9275dcc13b202fa1f0dc",
  "repo_slug": "bobbyhouse/project-gutenberg-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bobbyhouse_project_gutenberg_m_830d57b3/readme"
}