gitbook-mcp

MCP Server for full GitBook API automation. Exposes 39 tools that allow AI agents (Claude Code, Cursor, etc.) to manage documentation, change requests, reviews, and Git Sync programmatically.

Quickstart

# 1. Clone
git clone <your-repo-url>
cd gitbook-mcp

# 2. Install and build
npm install
npm run build

# 3. Configure
cp .env.example .env
# Edit .env with your token (see "Configuration" below)

# 4. Run
npm start

Configuration

Environment variables

Variable	Required	Description
GITBOOK_API_TOKEN	Yes	GitBook API token
GITBOOK_DEFAULT_ORG_ID	No	Default organization ID
GITBOOK_DEFAULT_SPACE_ID	No	Default space ID
GITBOOK_API_BASE_URL	No	API base URL (default: https://api.gitbook.com/v1)

Get your token

1. Go to GitBook Developer Settings
2. Create a new API Token
3. Copy the token to your .env

.env example

GITBOOK_API_TOKEN=gb_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITBOOK_DEFAULT_SPACE_ID=
GITBOOK_DEFAULT_ORG_ID=

AI Agent Integration

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "gitbook": {
      "command": "node",
      "args": ["/path/to/gitbook-mcp/dist/index.js"],
      "env": {
        "GITBOOK_API_TOKEN": "${GITBOOK_API_TOKEN}",
        "GITBOOK_DEFAULT_ORG_ID": ""
      }
    }
  }
}

Claude Code resolves ${GITBOOK_API_TOKEN} from shell environment variables. Add to your ~/.bashrc or ~/.zshrc:

export GITBOOK_API_TOKEN="your-token-here"

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "gitbook": {
      "command": "node",
      "args": ["/path/to/gitbook-mcp/dist/index.js"],
      "env": {
        "GITBOOK_API_TOKEN": "your-token-here",
        "GITBOOK_DEFAULT_ORG_ID": ""
      }
    }
  }
}

In Cursor, ${VAR} interpolation is not supported. Place the token directly in the JSON.

Other MCP clients

Any client compatible with MCP via stdio transport will work. The server reads stdin/stdout following the MCP protocol.

Tools

Spaces (6)

Tool	Description
get_space	Get space details
update_space	Update title, visibility
create_space	Create new space in an org
duplicate_space	Duplicate an existing space
list_spaces	List spaces in an org
search_space_content	Search content within a space

Pages (8)

Tool	Description
get_space_revision	Full page tree of a space
list_pages	List pages (with pagination)
get_page_by_id	Read page by ID
get_page_by_path	Read page by URL path (e.g., getting-started/install)
get_page_links	Outgoing links from a page
get_page_backlinks	Pages linking to a page (backlinks)
list_files	List files (images, attachments)
get_file	File details and download URL

Change Requests (6)

Tool	Description
create_change_request	Create new CR (similar to PR/draft)
list_change_requests	List CRs of a space
get_change_request	CR details
update_change_request	Update CR title/status
merge_change_request	Merge CR into main content
sync_change_request	Sync CR with latest content

Reviews (5)

Tool	Description
list_reviews	List reviews of a CR
submit_review	Approve, request changes, or comment
list_requested_reviewers	List requested reviewers
request_reviewers	Request review from specific users
remove_reviewer	Remove reviewer from a CR

Comments (6)

Tool	Description
list_comments	List comments (space or CR)
post_comment	Post comment (supports markdown)
update_comment	Edit existing comment
delete_comment	Delete comment
list_comment_replies	List replies to a comment
post_comment_reply	Reply to a comment

Git Sync (3)

Tool	Description
git_import	Import content from a Git repo to a space
git_export	Export content from a space to a Git repo
get_git_info	Git Sync status and configuration

Organizations (4)

Tool	Description
get_organization	Organization details
list_collections	List collections in an org
get_collection	Collection details
ask_ai	Ask GitBook AI about the documentation

Content Import (1)

Tool	Description
import_content	Import content from a URL into the org

Architecture

src/
├── index.ts                 # Entrypoint — stdio transport
├── server.ts                # McpServer creation
├── config.ts                # Environment variable loading
├── client/
│   ├── gitbook-client.ts    # HTTP client for GitBook API v1
│   └── types.ts             # API response types
├── tools/
│   ├── index.ts             # Registration of all 39 tools
│   ├── spaces.ts            # 6 tools
│   ├── pages.ts             # 8 tools
│   ├── change-requests.ts   # 6 tools
│   ├── reviews.ts           # 5 tools
│   ├── comments.ts          # 6 tools
│   ├── git-sync.ts          # 3 tools
│   ├── organizations.ts     # 4 tools
│   └── content-import.ts    # 1 tool
├── schemas/
│   └── index.ts             # Reusable Zod schemas
└── utils/
    ├── errors.ts            # API error handling
    └── pagination.ts        # Pagination helpers

Scripts

Command	Description
npm run build	Compile TypeScript to dist/
npm start	Start MCP server via stdio
npm run dev	Compile in watch mode (development)
npm run inspect	Open MCP Inspector for debugging

Requirements

• Node.js >= 18.0.0
• npm

Dependencies

Package	Version	Usage
@modelcontextprotocol/sdk	^1.12.0	Official MCP SDK
zod	^3.24.0	Schema validation
typescript	^5.7.0	(dev) Compilation

Debug

MCP Inspector

npm run inspect

Opens a web interface to test tools interactively.

Error logs

The server sends formatted errors back to the MCP client. GitBook API errors include:

• HTTP status code
• Failed endpoint
• GitBook error message

Common issues

Problem	Solution
GITBOOK_API_TOKEN is required	Set the environment variable or create the .env file
GitBook API error 401	Invalid or expired token — generate a new one
GitBook API error 403	Token lacks permission for the resource
GitBook API error 404	Incorrect space/page/org ID
Cannot find module dist/index.js	Run npm run build first

Update

cd ~/gitbook-mcp
git pull
npm install
npm run build

License

MIT