使用说明

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

Go to GitBook Developer Settings
Create a new API Token
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