gutenberg-mcp-server

---

概要

Project Gutenberg のパブリックドメイン書籍 78,000 冊以上を収録したライブラリです。タイトル、著者、トピック、言語で検索し、書籍の全メタデータを取得して、対応する UTF-8 プレーンテキスト版および HTML 版を扱いやすい分量に分割して読めます。

ツール

ツール	説明
gutenberg_search_books	タイトル、著者、トピック、言語、著者の生存期間でカタログを検索します。ページネーションと人気順での並べ替えに対応しています
gutenberg_get_book	ID で書籍の完全なメタデータ（著者、翻訳者、編集者、全形式のマップ、主題、著作権の状態）を取得します
gutenberg_get_text	ライセンスに関する定型文を除いた書籍のプレーンテキストを、offset/limit による分割で取得します
gutenberg_browse_popular	ダウンロード数上位の書籍を閲覧します。言語またはトピックによる絞り込みも可能です

---

機能リファレンス

gutenberg_search_books _tool

• フィルター：query（タイトル／著者の単語）、topic、languages（ISO 639-1）、author_year_start／author_year_end、ids、mime_type、copyright（"true"、"false"、"null"。false は米国でパブリックドメインであることを意味します）。ライブフォールバックでは 4 語を超えるクエリは拒否されます
• sort は popular（既定値）、または Gutenberg ID の ascending／descending です。1 ページあたり最大 32 冊です。ページを切り替えるには totalCount と hasMore を使用してください
• 各結果には is_readable（gutenberg_get_text で読めるかどうか）と has_plain_text が含まれます。query_requires_mirror、page_out_of_range、catalog_unavailable が発生すると失敗します

---

gutenberg_get_book _ツール

• formats マップ（MIME タイプ → ダウンロード URL）全体と、著者、翻訳者、編集者の生年・没年を返します
• is_readable、has_plain_text、summary、source_notes、download_count（累計ではなく、直近30日間のダウンロード数）も含まれます
• not_found または catalog_unavailable で失敗します

---

gutenberg_get_text _ツール

• 書籍を offset／limit のチャンク単位で読み取ります（limit のデフォルトは20,000、上限は50,000）。Gutenberg のライセンスヘッダーとフッターは取り除かれます。requestedLimit と appliedLimit でそれぞれの値を報告します
• UTF-8 のプレーンテキストを優先し、利用できない場合は HTML をテキストに変換します。どちらを使用したかは sourceFormat で示されます。totalChars、length、remainingChars、hasMore、provenance（ID、タイトル、ライセンス URL）を返します。次の offset の計算には limit ではなく length を使用してください
• not_found、audio_book（media_type "Sound"）、no_text_format、offset_out_of_range、text_file_not_found、text_fetch_rejected、invalid_text_response、text_fetch_failed、catalog_unavailable で失敗します

---

gutenberg_browse_popular _ツール

• ダウンロード数が直近30日間で多い順に、最大32件のタイトルを返します（limit のデフォルトは20）。上限は requestedLimit と appliedLimit で報告されます
• 省略可能な languages、topic、mime_type、copyright フィルターは、検索と同様に機能します。totalInCatalog にはカタログ内の総件数が示されます
• 出力には切り詰められたかどうかが示され、gutenberg_search_books を指す continuation が含まれます。結果が空の場合は通知とともに正常終了します。catalog_unavailable で失敗します

---

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ロギングを提供します。

Gutenberg 固有の機能：

• 検索と照会では、ローカルの SQLite+FTS5 カタログミラーを読み取ります。ミラーが未初期化の場合やレコードが見つからない場合は、Gutendex にフォールバックします
• Project Gutenberg のコンテンツミラーからプレーンテキスト全体を取得し、UTF-8／HTML にフォールバックします
• 書籍のテキストはテナントごとにキャッシュされるため、後続のチャンク読み取りでは再取得をスキップします
• API キーは不要です

エージェントに適した出力：

• すべての検索結果と閲覧結果に含まれる is_readable で、gutenberg_get_text が読み取れる版を確認できます
• offset、length、totalChars、remainingChars、hasMore により、順次読み取りを確実に行えます
• すべてのテキスト応答に含まれる provenance と sourceFormat により、出典表示と忠実性を確認できます

---

はじめに

公開ホストインスタンス

公開インスタンスは https://gutenberg.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を使用して、任意の MCP クライアントから接続してください：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "streamable-http",
      "url": "https://gutenberg.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

API キーは不要です。以下を MCP クライアントの設定ファイルに追加してください：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gutenberg-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gutenberg-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/gutenberg-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• API キーは不要です。Project Gutenberg のデータは自由に利用できます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/gutenberg-mcp-server.git

2. ディレクトリに移動します：

cd gutenberg-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if you need to override any defaults

---

設定

変数	説明	デフォルト
GUTENDEX_BASE_URL	Gutendex カタログ API のベース URL です。	https://gutendex.com/books/
GUTENBERG_TEXT_BASE_URL	/cache/epub ファイルツリーを提供するコンテンツミラーです。	https://gutenberg.pglaf.org
GUTENBERG_MIRROR_PATH	SQLite カタログのパスです。コンテナーでは永続ボリュームを使用してください。	./.mirror/gutenberg-catalog.sqlite
GUTENBERG_MIRROR_REFRESH_CRON	プロセス内カタログ更新の Cron スケジュールです。	未設定
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless です。createApp() でサーバーが宣言する stateless の設定を上書きします。	stateless
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします。	false

bun run mirror:init でローカルカタログを構築し、bun run mirror:verify で確認してください。サーバーは起動時にデータを収集せず、最初の収集が完了するまでは Gutendex を使用します。ホストのスケジューラーで bun run mirror:refresh を実行するか、GUTENBERG_MIRROR_REFRESH_CRON を設定して、カタログを最新の状態に保ってください。

---

サーバーの実行

ローカル開発

• ビルドと実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストの実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t gutenberg-mcp-server .
docker run --rm -p 3010:3010 gutenberg-mcp-server

Dockerfile のデフォルト設定は、HTTP トランスポート、ステートレスセッションモード、および /var/log/gutenberg-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

---

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/config/server-config.ts	サーバー固有の環境変数を解析します（Gutendex とファイルサーバーの URL 上書き設定）。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。
src/services/gutendex/	Gutendex カタログ API クライアントです。検索と書籍メタデータを扱います。
src/services/catalog-mirror/	ローカルの SQLite+FTS5 カタログミラーです。RDF の取り込みと読み取りヘルパーを提供します。
src/services/gutenberg-text/	プレーンテキスト全体の取得、定型文の除去、テナントごとのキャッシュ、およびチャンク分割を行います。
tests/	src/ に対応するユニットテストと統合テストです。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md / AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用してください
• src/index.ts のエントリー配列を介して新しいツールを登録してください
• 外部 API 呼び出しをラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足フィールドを捏造してはなりません

---

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

データの帰属

Project Gutenberg のデータはパブリックドメインです。カタログのメタデータは Gutendex を出典としています（MIT ライセンス）。

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。