Set up GitBook
Set up GitBook from a coding agent or AI assistant and publish a docs site, either new docs or docs moved from another tool.
This page is for AI agents helping someone set up GitBook. Your goal is a published docs site at a public URL, with either new docs or docs moved from another tool.
Check whether you already have GitBook tools
If GitBook MCP tools are already in this session, for example from the Claude, ChatGPT, or Cursor plugin, confirm they work with a read-only call: get_usage_guide with the topic onboarding. If it answers, ask the question in Step 1, then go to Step 4. You don't need to connect anything, hand off, or save a plan file.
If there are no GitBook tools, find your row:
A coding agent that can run commands and edit files
Connect GitBook, bring the person in once, publish
A hosted chat assistant, such as Claude.ai or ChatGPT
Only the person can add the GitBook plugin
Relay the plugin setup
Send the person these steps as a numbered list:
GitBook connects to me as a plugin. I can't add it myself, but you can in a few clicks:
If you don't have a GitBook account, create one and finish signup until you see your organization.
Approve the GitBook sign-in that opens.
Start a new conversation so the GitBook tools load.
Tell me when it's done, and I'll help you plan and publish your docs.
Then stop. The rest of this page is for agents that can run commands and edit files. In the new conversation, start again from Check whether you already have GitBook tools.
How GitBook setup works
GitBook needs an account. There's no way to publish a site and hand it over later, so the person signs up or signs in at least once. Plan around that moment: do all your prep first, send one short "your turn" message, then resume.
You have three tools. Pick by situation, not by preference:
Default. The client can reload its config, and the person can approve a browser sign-in.
OAuth in the browser
The MCP tools can't load in this session, for example because the client can't restart.
gitbook login in the browser
The MCP server is https://mcp.gitbook.com/mcp. It supports streamable HTTP only, not stdio or SSE.
Keep messages to the person short
Each message says what's done and the one thing they do next, in two or three sentences. Don't relay IDs, tokens, file paths, or command output. Give a link only when they need to open it now.
Step 1: ask what they're doing
Before you configure anything, ask:
Are you starting new docs, or moving docs you already have?
Starting new. Ask what the docs are for and who reads them. If there's a codebase here, read it so you can propose real pages.
Moving docs. Ask where they live now: a folder or Git repository, a published website, or another tool such as Confluence or Notion. If they're on this machine, read them and say back what you found so they can confirm.
Draft a short plan: site title, page structure, and how the content gets in (see Moving existing docs). Save it to gitbook-setup-plan.md in the working directory, and don't commit it. The restart in Step 3 ends your session, and the plan file is how you pick up again.
Step 2: connect GitBook MCP
Ground rules
Read before you write. Config files hold the person's other MCP servers. Read the file, back it up if it exists, add or update only the
gitbookentry, and confirm the result parses.Say which file you're about to change before you change it.
If Claude Code's auto mode blocks a command, don't retry it or route around it. Hand-editing the config is the same action it refused. Tell the person what the command does and let them run it.
Work out which client you're running in. If you can't tell, ask. A config in the wrong place fails silently.
Claude Code
--scope user makes GitBook available in every project. Without it, the server only exists in the current directory. Check it registered with claude mcp get gitbook. To undo, run claude mcp remove gitbook --scope user.
After a restart, the person types /mcp and picks GitBook to sign in. That's a slash command, so you can't run it for them.
Codex
The browser sign-in starts after you add it. Check it with codex mcp get gitbook, and retry a sign-in with codex mcp login gitbook. To undo, run codex mcp remove gitbook. The tools load in a new Codex task.
Cursor
The person can install the GitBook plugin for Cursor. To configure it yourself, add this to ~/.cursor/mcp.json, or to .cursor/mcp.json for this project only:
Cursor prompts for the sign-in. Leave auth fields out.
VS Code
Add this to .vscode/mcp.json in the workspace:
The person starts it from the MCP view and signs in.
Other clients
Add a remote streamable HTTP server at https://mcp.gitbook.com/mcp. With OAuth, the client handles the sign-in and you add no auth fields. If the client can't do OAuth, send a personal access token as Authorization: Bearer <token>. The person creates it in their developer settings.
Verify before the restart
Re-read the file you changed, or run the client's get command, and confirm the gitbook entry is there and the file parses. The restart ends your session, so check now.
Optional: add GitBook skills
You don't need skills to publish, but they help the first pages come out right. The write-docs skill teaches GitBook-flavored Markdown, such as hints, tabs, and steppers, so pages render correctly in GitBook. Tell the person what you're installing, then run:
Without both -y flags, the installer waits for input. If Claude Code's auto mode blocks the command, hand it to the person instead. Don't commit the installed skill files unless they ask.
The GitBook skills repository includes write-docs, configure-site, write-openapi, cr-create, cr-review, and build-integration, for pages, site setup, OpenAPI references, change requests, and integrations.
Step 3: hand off once
Send one message that covers everything the person needs to do:
I've added GitBook to [client] and saved our plan. Your turn:
If you don't have a GitBook account, create one and finish signup until you see your organization.
Restart [client], then sign in to GitBook when it asks. In Claude Code, type
/mcpand pick GitBook.Tell me "done" and I'll pick up from the plan.
To undo this, [how to undo for this client].
If the session can't restart, don't wait. Use the CLI instead.
Step 4: resume and publish
Read
gitbook-setup-plan.md, if you saved one.Call
get_usage_guidewith the topiconboarding, and follow it. Useeditingfor adding content.List the person's organizations with
invoke_operationandlistOrganizationsForAuthenticatedUser. Ask which one to use, even if there's only one.Call
get_subscription_information. If the organization isn't on a paid plan, create the site withtypeset tobasic. Other types can return a checkout instead of a published site.Create the site and add the content, following the plan.
Show the person what you're about to publish and wait for a yes. Merging a change request and publishing a site are public and can't be undone.
Publish, then go to Step 5.
Moving existing docs
Only route content through paths that exist. For Markdown already in a GitHub or GitLab repository, including exports from another docs tool, use Git Sync. It's the recommended path for large migrations and supports up to 5,000 pages. Create the site with no spaces and don't apply the template. Git Sync setup isn't available through the MCP, so the person connects it in the GitBook app and picks the direction GitHub → GitBook. Warn them that the other direction can overwrite the repository. The Git Sync migration guide has the steps. Resume when they confirm the sync finished.
When the person names a source, use this table:
Mintlify
Docs are Markdown or MDX in a Git repo, so use Git Sync. Mintlify-specific MDX components may need converting to GitBook blocks. The agent can do that in the repo before the person connects Git Sync.
Agent prepares the repo. Person connects Git Sync in the GitBook app.
Docusaurus
Docs are Markdown or MDX in a Git repo, so use Git Sync.
Agent prepares the repo. Person connects Git Sync in the GitBook app.
ReadMe
If the project already uses Git Connection, the docs are Markdown or MDX in a Git repo. Use Git Sync. If not, the person can connect Git Connection to an empty repo (ReadMe writes the files), or export Guides as Markdown with rdme docs export. Then use Git Sync. If neither export is available, the person uses the Import panel on the published site (20-page cap).
Agent prepares the repo once the Markdown is available. Person enables Git Connection or exports, then connects Git Sync, or uses the Import panel.
Confluence, Notion, Google Docs, Word, or other published sites
The person uses the Import panel in the GitBook app. It takes up to 20 pages per import.
The person runs the import.
A few Markdown files on this machine
Add them as pages in a change request, the same way you'd add new content.
The agent adds the pages.
Name the human step plainly in your plan, and put it in the Step 3 message so it happens in the same hand-off.
Step 5: verify and report
Read the published URL from the publish response, open it, and confirm the content is live. Then tell the person in two or three sentences: what's published, the link, and one suggested next step. Delete gitbook-setup-plan.md if they don't want it.
Suggested first tasks:
Fallback: the GitBook CLI
Use the CLI when the MCP tools can't load in this session, for example because the client can't restart. The CLI needs Node v18 or later:
Sign in with gitbook login. It opens GitBook in the browser, and the sign-in returns to a localhost callback on the machine running the CLI. On the person's own machine, run it in the background and tell them to approve the sign-in in the browser. In a cloud or remote session, the browser can't reach that callback, so the person runs gitbook login in their own terminal.
Confirm with gitbook whoami, then run the flow below. Add --json to every command so you can parse the output, show each command before you run it, and stop if one fails.
List organizations and ask which one to use:
Create a space and copy its
id. The body is JSON, not a--titleflag, and titles are capped at 50 characters:
Add content through a change request, then merge it:
A single # heading becomes the page title, so use ## and below inside the page.
Create the site with the space attached. Use
--type basicunless the organization has a paid plan:
Publish and read
urls.publishedfrom the output:
The CLI guide has more detail.
When neither covers a step
Use the GitBook API with a personal access token. With the MCP connected, search, describe_operation, and invoke_operation reach most API operations without leaving the session.
Stuck, or something here is wrong?
Ask the docs. Send a GET request to any GitBook docs page URL ending in
.md, withaskset to your question andgoalset to what the person wants to achieve. For example:https://gitbook.com/docs/setup.md?ask=<question>&goal=<goal>.Report it. With the MCP connected, call
report_tool_feedbackwith what you tried and what happened. Leave tokens and private content out.
Last updated
Was this helpful?