> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/setup.md).

# GitBookをセットアップする

コーディングエージェントやAIアシスタントからGitBookをセットアップし、新しいドキュメント、または別のツールから移行したドキュメントのサイトを公開します。

このページは、誰かがGitBookをセットアップするのを支援するAIエージェント向けです。目標は、新しいドキュメントを作成するか、別のツールから移行して、公開URLで公開されたドキュメントサイトを用意することです。

{% hint style="info" %}
**人が操作する場合**

まず [クイックスタート](https://gitbook.com/docs/getting-started/quickstart)をご覧ください。セットアップをコーディングエージェントに任せるには、次のプロンプトを貼り付けてください。 `Set up GitBook for me by following https://gitbook.com/docs/setup.md`.
{% endhint %}

## GitBookツールがすでに使えるか確認する

たとえばClaude、ChatGPT、Cursorのプラグイン経由で、このセッションですでにGitBook MCPツールを使える場合は、読み取り専用の呼び出しで動作を確認してください。 `get_usage_guide` をトピック `onboarding`を指定して実行します。応答があれば、 [ステップ1](#step-1-ask-what-theyre-doing)の質問をしてから、 [ステップ4](#step-4-resume-and-publish)に進んでください。接続や引き継ぎ、計画ファイルの保存は不要です。

GitBookツールが使えない場合は、該当する行を確認してください。

| 利用者                                | できること                              | 次に進む先                                                           |
| ---------------------------------- | ---------------------------------- | --------------------------------------------------------------- |
| コマンドを実行してファイルを編集できるコーディングエージェント    | GitBookを接続し、一度だけ利用者に操作してもらってから公開する | [GitBookのセットアップ方法](#how-gitbook-setup-works)                    |
| Claude.aiやChatGPTなどのホスト型チャットアシスタント | GitBookプラグインを追加できるのは利用者だけ          | [プラグインのセットアップ手順を伝える](#relay-the-plugin-setup)                   |
| 利用者本人                              | アプリでセットアップするか、エージェントに任せる           | [クイックスタート](https://gitbook.com/docs/getting-started/quickstart) |

### プラグインのセットアップ手順を伝える

次の手順を番号付きリストで利用者に送ってください。

> GitBookはプラグインとして私に接続します。私自身では追加できませんが、数回クリックするだけで追加できます。
>
> 1. GitBookアカウントをお持ちでない場合は、 [アカウントを作成し、](https://app.gitbook.com/join) 組織が表示されるまで登録を完了してください。
> 2. GitBookプラグインをインストールします。 [Claude](https://claude.ai/directory/connectors/gitbook-mcp) または [ChatGPT](https://chatgpt.com/apps/gitbook/asdk_app_6a576f075ec4819196c203b7049542be).
> 3. ブラウザーで開くGitBookへのサインインを承認します。
> 4. 新しい会話を開始して、GitBookツールを読み込みます。
>
> 完了したら知らせてください。ドキュメントの計画と公開をお手伝いします。

その後は停止してください。このページの残りは、コマンドを実行してファイルを編集できるエージェント向けです。新しい会話では、もう一度 [GitBookツールがすでに使えるか確認する](#check-whether-you-already-have-gitbook-tools).

## GitBookのセットアップ方法

GitBookを使うにはアカウントが必要です。サイトを公開して後から引き継ぐ方法はないため、利用者は少なくとも一度、登録またはサインインする必要があります。そのタイミングを考慮して準備を先にすべて済ませ、「あなたの番です」という短いメッセージを一度送ってから、作業を再開してください。

利用状況に応じて、3つのツールから選んでください。好みで選ぶものではありません。

| ツール                                                                                                        | こんなときに使います                                              | サインイン方法                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------- |
| [GitBook MCP](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/gitbook-mcp.md) | 標準の方法です。クライアントが設定を再読み込みでき、利用者はブラウザーでのサインインを承認できます。      | ブラウザーでOAuth               |
| [GitBook CLI](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/gitbook-cli.md) | たとえばクライアントを再起動できないなどの理由で、このセッションではMCPツールを読み込めない場合に使います。 | `gitbook login` をブラウザーで実行 |
| [GitBook API](https://gitbook.com/docs/developers/gitbook-api/api-reference)                               | MCPでもCLIでもカバーされない手順です。                                  | 個人アクセストークン                |

MCPサーバーのURLは `https://mcp.gitbook.com/mcp`です。対応しているのはストリーミング可能なHTTPのみで、 `stdio` や `SSE`.

## 相手へのメッセージは短くする

各メッセージでは、完了したことと、次に相手が行うことを1つ、2〜3文で伝えます。ID、トークン、ファイルパス、コマンド出力は伝えません。今すぐ開く必要がある場合に限り、リンクを提示します。

## ステップ1：何をしているのか尋ねる

何かを設定する前に、次のように尋ねます。

> 新しいドキュメントを作成しますか？それとも、既存のドキュメントを移行しますか？

* **新しく作成する。** ドキュメントの目的と対象読者を尋ねます。ここにコードベースがある場合は、それを読み、実際のページ案を提示できるようにします。
* **ドキュメントを移行する。** 現在の保存場所を尋ねます。フォルダーやGitリポジトリ、公開済みのウェブサイト、ConfluenceやNotionなどの別のツールのいずれでしょうか。このマシン上にある場合は内容を読み、見つけたものを伝えて確認してもらいます。

簡潔な計画を作成します。サイトのタイトル、ページ構成、コンテンツの取り込み方法をまとめます（ [既存ドキュメントの移行](#moving-existing-docs)を参照）。作業ディレクトリに `gitbook-setup-plan.md` として保存し、コミットしないでください。ステップ3での再起動によりセッションが終了するため、計画ファイルを使って作業を再開します。

## ステップ2：GitBook MCPに接続する

### 基本ルール

* **書き込む前に読みます。** 設定ファイルには、相手が使用しているほかのMCPサーバーも記載されています。ファイルを読み、存在する場合はバックアップを取り、 `gitbook` のエントリーだけを追加または更新し、設定が正しく解析できることを確認します。
* 変更する前に、これから変更するファイルを伝えます。
* **Claude Codeの自動モードでコマンドがブロックされた場合、再試行したり、別の方法で回避したりしないでください。** 設定を手作業で編集するのも、拒否された操作と同じです。コマンドの動作を相手に説明し、実行してもらいます。

使用中のクライアントを特定します。判別できない場合は尋ねてください。誤った場所に設定すると、エラーが表示されないまま機能しません。

### Claude Code

```bash
claude mcp add --transport http --scope user gitbook https://mcp.gitbook.com/mcp
```

`--scope user` を指定すると、すべてのプロジェクトでGitBookを利用できます。指定しない場合、サーバーは現在のディレクトリでのみ有効です。次のコマンドで登録を確認します。 `claude mcp get gitbook`。元に戻すには、次を実行します。 `claude mcp remove gitbook --scope user`.

再起動後、相手は `/mcp` と入力し、GitBookを選んでサインインします。これはスラッシュコマンドなので、代わりに実行することはできません。

### Codex

```bash
codex mcp add gitbook --url https://mcp.gitbook.com/mcp
```

追加後、ブラウザーでのサインインが始まります。次のコマンドで確認します。 `codex mcp get gitbook`。サインインをやり直すには、次を実行します。 `codex mcp login gitbook`。元に戻すには、次を実行します。 `codex mcp remove gitbook`ツールは新しいCodexタスクで読み込まれます。

### Cursor

相手は [Cursor用のGitBookプラグインをインストールできます](https://cursor.com/marketplace/gitbook)。自分で設定するには、これを次に追加します： `~/.cursor/mcp.json`、または次に追加します： `.cursor/mcp.json` このプロジェクトのみに適用する場合：

```json
{
  "mcpServers": {
    "gitbook": {
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

サインインを求めるのは Cursor です。認証フィールドは含めないでください。

### VS Code

これを次に追加します： `.vscode/mcp.json` ワークスペース内の：

```json
{
  "servers": {
    "gitbook": {
      "type": "http",
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

ユーザーは MCP ビューから起動し、サインインします。

### その他のクライアント

リモートのストリーミング可能なHTTPサーバーを次の場所に追加します： `https://mcp.gitbook.com/mcp`。OAuthを使う場合、サインインはクライアントが処理するため、認証フィールドを追加する必要はありません。クライアントがOAuthに対応していない場合は、個人用アクセストークンを次のように送信します： `Authorization: Bearer <token>`トークンは、ユーザーが次の場所で作成します： [開発者設定](https://app.gitbook.com/account/developer).

### 再起動する前に確認する

変更したファイルを再度読み込むか、クライアントの次のコマンドを実行します： `get` コマンドを実行し、 `gitbook` のエントリが存在し、ファイルを解析できることを確認します。再起動するとセッションが終了するため、今のうちに確認してください。

### 任意: GitBook のスキルを追加する

公開にスキルは必須ではありませんが、最初のページを適切に作成するのに役立ちます。 `write-docs` スキルでは、ヒント、タブ、ステッパーなどの GitBook 独自の Markdown を学べるため、ページが GitBook で正しく表示されます。インストールするものを伝えてから、次を実行します。

```bash
npx -y skills add GitbookIO/gitbook-skills -y
```

両方の `-y` フラグを指定しない場合、インストーラーは入力待ちになります。Claude Code の自動モードによってコマンドがブロックされた場合は、代わりに担当者に実行してもらってください。依頼されない限り、インストールしたスキルファイルはコミットしないでください。

この [GitBook スキルリポジトリ](https://github.com/GitbookIO/gitbook-skills) には、 `write-docs`, `configure-site`, `write-openapi`, `cr-create`, `cr-review`、および `build-integration`。ページ、サイトの設定、OpenAPI リファレンス、変更リクエスト、インテグレーションに使用します。

## ステップ 3: 一度だけ引き継ぐ

相手が行う必要のあることをすべてまとめて、メッセージを 1 つ送信します。

> \[client] に GitBook を追加し、計画を保存しました。次はあなたの番です。
>
> 1. GitBookアカウントをお持ちでない場合は、 [アカウントを作成し、](https://app.gitbook.com/join) 組織が表示されるまで登録を完了してください。
> 2. \[client] を再起動し、表示されたら GitBook にサインインしてください。Claude Code で次のように入力します。 `/mcp` 次に GitBook を選択します。
> 3. 「完了」と伝えてください。計画に沿ってこちらで続けます。
>
> これを元に戻すには、\[このクライアントで元に戻す方法] を参照してください。

セッションを再開できない場合は、待たずに [CLI](#fallback-the-gitbook-cli) を使ってください。

## ステップ 4：再開して公開する

1. 保存してある場合は、 `gitbook-setup-plan.md`を読みます。
2. トピックに `get_usage_guide` を指定して呼び出し、 `onboarding`の手順に従います。コンテンツの追加には `editing` を使います。
3. 認証済みユーザーの組織を `invoke_operation` と `listOrganizationsForAuthenticatedUser`を使って一覧表示します。組織が1つしかない場合でも、どれを使うか尋ねてください。
4. get\_subscription\_information `を呼び出します。`組織が有料プランを利用していない場合は、 `type` を `basic`に設定してサイトを作成します。他のタイプでは、公開済みサイトではなくチェックアウトが返されることがあります。
5. プランに従ってサイトを作成し、コンテンツを追加します。
6. 公開しようとしている内容を相手に見せ、承認を待ちます。変更リクエストのマージもサイトの公開も公開操作であり、取り消せません。
7. 公開したら、 [ステップ 5](#step-5-verify-and-report).

### 既存のドキュメントを移行する

存在するパスのみを使ってコンテンツをルーティングしてください。GitHub または GitLab のリポジトリにある Markdown（別のドキュメントツールからエクスポートしたものを含む）には、 [Git Sync](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync.md)を使用します。大規模な移行に推奨される方法で、最大 5,000 ページに対応しています。サイトはスペースを含まない名前で作成し、テンプレートは適用しないでください。Git Sync の設定は MCP からは行えないため、担当者が GitBook アプリで接続し、同期方向として **GitHub → GitBook**を選択します。逆方向ではリポジトリが上書きされる可能性があることを伝えてください。手順は [Git Sync 移行ガイド](https://gitbook.com/docs/guides/editing-and-publishing-documentation/import-or-migrate-your-content-to-gitbook-with-git-sync) に記載されています。同期が完了したことを担当者が確認したら、作業を再開してください。

担当者が移行元を指定した場合は、次の表を参照してください。

| ソース                                          | ルート                                                                                                                                                                                                                                                                                                                                                                                                                                               | 担当者とエージェントの役割                                                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Mintlify                                     | ドキュメントは Git リポジトリ内の Markdown または MDX なので、Git Sync を使用します。Mintlify 固有の MDX コンポーネントは GitBook ブロックに変換する必要がある場合があります。担当者が Git Sync を接続する前に、エージェントがリポジトリ内で変換できます。                                                                                                                                                                                                                                                                                      | エージェントがリポジトリを準備します。担当者が GitBook アプリで Git Sync を接続します。                                                             |
| Docusaurus                                   | ドキュメントは Git リポジトリ内の Markdown または MDX なので、Git Sync を使用します。                                                                                                                                                                                                                                                                                                                                                                                         | エージェントがリポジトリを準備します。担当者が GitBook アプリで Git Sync を接続します。                                                             |
| ReadMe                                       | プロジェクトですでに [Git Connection](https://docs.readme.com/main/docs/bi-directional-sync)を使用している場合、ドキュメントは Git リポジトリ内の Markdown または MDX です。Git Sync を使用します。使用していない場合は、担当者が空のリポジトリに Git Connection を接続できます（ReadMe がファイルを書き込みます）。または、 [`rdme docs export`](https://github.com/readmeio/rdme/blob/main/documentation/commands/docs.md)を使って Guides を Markdown としてエクスポートできます。その後、Git Sync を使用します。どちらの方法でもエクスポートできない場合は、公開サイトの Import パネルを使用します（1回につき最大20ページ）。 | Markdown が用意できたら、エージェントがリポジトリを準備します。担当者は Git Connection を有効にするか、ファイルをエクスポートしてから Git Sync を接続するか、Import パネルを使用します。 |
| Confluence、Notion、Google Docs、Word、その他の公開サイト | 担当者は GitBook アプリの [Import パネル](https://gitbook.com/docs/documentation/ja-gitbook-documentation/getting-started/import.md) を使用します。1回のインポートで最大20ページを取り込めます。                                                                                                                                                                                                                                                                                         | 担当者がインポートを実行します。                                                                                                  |
| このマシン上にある少数の Markdown ファイル                   | 新しいコンテンツを追加するときと同じ方法で、変更リクエストにページとして追加します。                                                                                                                                                                                                                                                                                                                                                                                                        | エージェントがページを追加します。                                                                                                 |

人が行う手順は、計画内で明確に示し、ステップ 3 のメッセージにも記載して、同じ引き継ぎの中で実行されるようにします。

## ステップ 5：確認して報告する

公開への応答から公開 URL を読み取り、その URL を開いてコンテンツが公開されていることを確認します。その後、公開した内容、リンク、次に推奨する手順を、2～3文で相手に伝えます。 `gitbook-setup-plan.md` 不要なら。

最初におすすめのタスク：

```
このリポジトリのREADMEを基に、GitBookサイトにスタートガイドのページを追加する
今週の変更内容をまとめたリリースノートをGitBookで変更リクエストとして作成する
```

## 代替手段：GitBook CLI

このセッションでMCPツールを読み込めない場合（たとえば、クライアントを再起動できない場合）はCLIを使います。CLIにはNode v18以降が必要です。

```bash
npm install @gitbook/cli -g
```

**次のコマンドでサインインします： `gitbook login`.** このコマンドを実行するとブラウザーでGitBookが開き、サインイン後、CLIを実行しているマシン上のlocalhostコールバックに戻ります。本人のマシンで実行する場合は、バックグラウンドで起動し、ブラウザーでサインインを承認するよう案内してください。クラウド環境やリモートセッションでは、ブラウザーからそのコールバックにアクセスできないため、本人に `gitbook login` 自分のターミナルで実行してもらいます。

次のコマンドで確認します： `gitbook whoami`。その後、以下の手順を実行します。すべてのコマンドに `--json` を追加して出力を解析できるようにします。各コマンドは実行前に表示し、失敗した場合は中止してください。

1. 組織の一覧を表示し、使用する組織を尋ねます：

```bash
gitbook organizations list
```

2. スペースを作成し、その `id`をコピーします。本文はJSONであり、 `--title` フラグではありません。また、タイトルは50文字以内です：

```bash
gitbook spaces create <organizationId> --body '{"title":"Product docs"}'
```

3. 変更リクエストでコンテンツを追加し、マージします：

```bash
gitbook spaces change-requests create <spaceId> --subject "Add homepage"
```

```bash
gitbook spaces change-requests content update <spaceId> <changeRequestId> --changes '[
  {
    "operation": "insert_page",
    "title": "Welcome",
    "document": {
      "markdown": "# Welcome\n\nThis page was published from the command line.\n"
    }
  }
]'
```

```bash
gitbook spaces change-requests merge <spaceId> <changeRequestId>
```

見出しは1つだけにし、 `#` これをページタイトルにします。ページ本文では `##` 以降の見出しを使ってください。

4. スペースを紐付けてサイトを作成します。組織が有料プランでない場合は、 `--type basic` を指定してください：

```bash
gitbook organizations sites create <organizationId> --type basic --title "Product docs" --visibility public --spaces '["<spaceId>"]'
```

5. 公開し、出力から `urls.published` を確認します：

```bash
gitbook organizations sites publish <organizationId> <siteId> --full
```

詳しくは [CLIガイド](https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line) をご覧ください。

## どちらの方法でも手順を実行できない場合

個人用アクセストークンを使って [GitBook API](https://gitbook.com/docs/developers/gitbook-api/api-reference) を利用します。MCPが接続されていれば、セッションを離れずに `search`, `describe_operation`と `invoke_operation` を使って、ほとんどのAPI操作を実行できます。

## 行き詰まった場合や、ここに誤りがある場合は

* **ドキュメントに質問してください。** 末尾が `.md`のGitBookドキュメントページURLに、GETリクエストを送信し、 `ask` 質問を設定し、 `goal` 達成したいことを設定します。例： `https://gitbook.com/docs/setup.md?ask=<question>&goal=<goal>`.
* **報告してください。** MCPに接続した状態で、 `report_tool_feedback` を呼び出し、試したこととその結果を伝えてください。トークンや個人情報は含めないでください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
