Configure GitBook Site

A skill for creating and maintaining entire GitBook documentation sites. Where write-docs covers what goes inside a single page, this skill covers everything around the pages: structure design, repo scaffolding, the GitBook API, and branding. Use the two skills together — this one calls into write-docs whenever it needs to generate or edit page content.

How you can talk to GitBook

There's more than one way to drive GitBook — GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer MCP first: if GitBook MCP tools are already connected, use them for anything they cover (creating/configuring sites, opening change requests, drafting and editing content, restructuring docs) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

"MCP first" is about transport, not about bypassing Git Sync for content. MCP exposes a change-request content-push tool (updateChangeRequestContent) that's tempting to reach for anytime it's connected — but for spaces that already have Git Sync configured, pushing content by editing files in the local repo and letting Git Sync carry it to GitBook is still the preferred path for anything beyond a small, targeted edit. Use the change-request push (MCP or REST) instead when the space isn't Git-synced, there's no local checkout available in the environment, or the edit is small enough that opening a CR is proportionate. See write-docs's "Choosing Git Sync vs. a change-request content push" for the full rule — it applies here too.

The steps in this skill are described as outcomes ("list the orgs", "create the site", "add a section") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints, request bodies, and expected responses for each step are in references/api-cheatsheet.md.

• GitBook MCP — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (a full site build, ongoing restructuring — not a one-off tweak), offer to set it up: claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp (then /mcp to complete OAuth sign-in — or append --header "Authorization: Bearer $GITBOOK_TOKEN" to skip the browser flow). Codex equivalent: codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp. Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
• REST API (https://api.gitbook.com/v1) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs GITBOOK_TOKEN as a bearer header on every request.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer token for both. MCP additionally supports OAuth as a friendlier alternative to pasting a token.

If you end up needing a token (REST API path, or MCP without OAuth), check for it at the start of the session: