GitBook MCP Server Reference

A Model Context Protocol (MCP) server that provides access to GitBook's API for AI assistants and LLM applications.

Overview

The GitBook MCP server enables programmatic access to GitBook Organizations, Spaces, Collections, and Content through a standardized MCP interface. It provides 12 tools for content operations and 6 AI-powered prompts for documentation workflows.

Quick Setup

Prerequisites

GitBook API token (obtain from https://app.gitbook.com/account/developer)
Your GitBook Organization ID (optional but recommended)

IDE and AI Assistant Integration

VS Code (with GitHub Copilot)

Add to your VS Code MCP settings:

{
    "servers": {
        "gitbook-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "gitbook-mcp",
                "--organization-id=your_organization_id_here"
            ],
            "env": {
                "GITBOOK_API_TOKEN": "gb_api_your_token_here"
            }
        }
    }
}

Claude Desktop

Add to your Claude Desktop configuration (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
    "mcpServers": {
        "gitbook-mcp": {
            "command": "npx",
            "args": ["gitbook-mcp", "--organization-id=your_organization_id"],
            "env": {
                "GITBOOK_API_TOKEN": "gb_api_your_token_here"
            }
        }
    }
}

See https://modelcontextprotocol.io/quickstart/user for details.

GitHub Copilot plugin for JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.):

Add to your GitHub Copilot MCP settings for JetBrains IDEs (the path may vary by product and OS, e.g., ~/.config/github-copilot/intellij/mcp.json for IntelliJ on Linux/macOS, or the equivalent directory for your JetBrains IDE and platform):

{
    "servers": {
        "gitbook-mcp": {
            "command": "npx",
            "args": [
                "gitbook-mcp",
                "--organization-id=your_organization_id_here"
            ],
            "env": {
                "GITBOOK_API_TOKEN": "gb_api_your_token_here"
            }
        }
    }
}

JetBrains AI Assistant

Add to your JetBrains AI Assistant MCP configuration (see official docs for the exact path):

Getting Your GitBook Credentials

API Token: Visit https://app.gitbook.com/account/developer to generate your API token
Organization ID: Use the list_organizations tool after setup to find your organization ID
Space ID (optional): Use the list_spaces tool (requires a valid organization ID and API token) to find specific space IDs
Space ID (optional): Use the list_spaces tool to find specific space IDs

Configuration Options

You can configure the server using:

CLI arguments: --organization-id, --space-id
Environment variables in MCP config: Set via the env object in your MCP configuration
System environment variables: GITBOOK_API_TOKEN, GITBOOK_ORGANIZATION_ID, GITBOOK_SPACE_ID

Note: .env files are only supported when running the server locally for development, not when using npx gitbook-mcp.

API Reference

Tools

The GitBook MCP server provides 12 tools organized into functional categories. Each tool includes behavioral hints:

📖 Read-only: Tool only reads data and doesn't modify anything
🔄 Idempotent: Repeated calls with same args have no additional effect with the same result
🌐 Open-world: Tool interacts with external entities

Organization Discovery

List Organizations (`list_organizations`) 📖 🔄 🌐

Lists all accessible GitBook organizations.

Parameters: None

Returns:

{
    "organizations": [
        {
            "id": "string",
            "title": "string",
            "urls": {
                "app": "string",
                "public": "string"
            }
        }
    ]
}

Space Management

List Spaces (`list_spaces`) 📖 🔄 🌐

Lists spaces, optionally filtered by organization.

Parameters:

organizationId (optional): Organization ID to filter spaces

Returns:

{
    "spaces": [
        {
            "id": "string",
            "title": "string",
            "visibility": "string",
            "urls": {
                "app": "string",
                "public": "string"
            }
        }
    ]
}

Get Space Details (`get_space`) 📖 🔄 🌐

Retrieves detailed information about a specific space.

Parameters:

spaceId (required): The ID of the space to retrieve

Returns:

{
    "id": "string",
    "title": "string",
    "description": "string",
    "visibility": "string",
    "urls": {
        "app": "string",
        "public": "string"
    }
}

Get Space Content (`get_space_content`) 📖 🔄 🌐

Retrieves the content structure and pages of a space.

Parameters:

spaceId (optional): The ID of the space (uses default if configured)

Returns:

{
    "pages": [
        {
            "id": "string",
            "title": "string",
            "slug": "string",
            "path": "string"
        }
    ]
}

Search Content (`search_content`) 📖 🔄 🌐

Searches for content within a space using full-text search.

Parameters:

query (required): Search query string
spaceId (optional): The ID of the space to search (uses default if configured)

Returns:

{
    "results": [
        {
            "id": "string",
            "title": "string",
            "excerpt": "string",
            "url": "string"
        }
    ]
}

Content Retrieval

Get Page Content (`get_page_content`) 📖 🔄 🌐

Retrieves the content of a specific page.

Parameters:

pageId (required): The ID of the page to retrieve
spaceId (optional): The ID of the space containing the page
format (optional): Output format ("document" or "markdown", defaults to "document")
metadata (optional): Include revision metadata (boolean, defaults to false)
computed (optional): Include computed revision data (boolean, defaults to false)

Returns:

{
    "id": "string",
    "title": "string",
    "content": "string",
    "format": "string"
}

Get Page by Path (`get_page_by_path`) 📖 🔄 🌐

Retrieves page content using the page path.

Parameters:

pagePath (required): The path of the page to retrieve
spaceId (optional): The ID of the space containing the page

Returns:

{
    "id": "string",
    "title": "string",
    "content": "string",
    "path": "string"
}

File Management

Get Space Files (`get_space_files`) 📖 🔄 🌐

Lists all files in a space.

Parameters:

spaceId (optional): The ID of the space (uses default if configured)

Returns:

{
    "files": [
        {
            "id": "string",
            "name": "string",
            "downloadURL": "string",
            "size": "number"
        }
    ]
}

Get File Details (`get_file`) 📖 🔄 🌐

Retrieves details of a specific file.

Parameters:

fileId (required): The ID of the file to retrieve
spaceId (optional): The ID of the space containing the file

Returns:

{
    "id": "string",
    "name": "string",
    "downloadURL": "string",
    "size": "number",
    "uploadedAt": "string"
}

Collection Management

List Collections (`list_collections`) 📖 🔄 🌐

Lists all accessible collections.

Parameters:

organizationId (optional): Organization ID to filter collections

Returns:

{
    "collections": [
        {
            "id": "string",
            "title": "string",
            "description": "string"
        }
    ]
}

Get Collection Details (`get_collection`) 📖 🔄 🌐

Retrieves details of a specific collection.

Parameters:

collectionId (required): The ID of the collection to retrieve

Returns:

{
    "id": "string",
    "title": "string",
    "description": "string",
    "spaces": "number"
}

Get Collection Spaces (`get_collection_spaces`) 📖 🔄 🌐

Lists all spaces within a collection.

Parameters:

collectionId (required): The ID of the collection

Returns:

{
    "spaces": [
        {
            "id": "string",
            "title": "string",
            "visibility": "string"
        }
    ]
}

Prompts

The GitBook MCP server provides 6 AI-powered prompts for documentation workflows:

Fetch Documentation (`fetch_documentation`)

Fetches and analyzes GitBook documentation content for specific topics.

Parameters:

topic (required): The topic or subject to search for and analyze
spaceId (optional): The ID of the space to search (uses default if configured)
includeStructure (optional): Set to "true" to include space structure

Returns: A comprehensive analysis of documentation related to the specified topic, including:

Relevant pages and sections
Content summaries
Gaps or areas needing improvement

Analyze Content Gaps (`analyze_content_gaps`)

Identifies gaps and missing content in documentation.

Parameters:

spaceId (optional): The ID of the space to analyze (uses default if configured)
comparisonSource (optional): Source to compare against (default: "internal analysis")

Returns: A detailed gap analysis including:

Missing topics and incomplete sections
Coverage gaps prioritized by importance
Suggestions for new content areas

Content Audit (`content_audit`)

Performs quality audits of documentation content.

Parameters:

spaceId (optional): The ID of the space to audit (uses default if configured)
auditCriteria (optional): Specific criteria to audit (default: "general quality and consistency")

Returns: A comprehensive quality assessment including:

Content quality and consistency review
Outdated information identification
Writing style and formatting recommendations

Documentation Summary (`documentation_summary`)

Generates comprehensive summaries of GitBook spaces.

Parameters:

spaceId (optional): The ID of the space to summarize (uses default if configured)
summaryType (optional): Type of summary - "overview", "technical", "user-guide", or "custom" (default: "overview")

Returns: A structured summary including:

Space structure and content organization
Main topics and themes
Target audience and use cases

Content Optimization (`content_optimization`)

Optimizes content for SEO, readability, structure, or performance.

Parameters:

spaceId (optional): The ID of the space to optimize (uses default if configured)
optimizationType (required): Type of optimization - "SEO", "readability", "structure", or "performance"
targetMetrics (optional): Specific metrics or goals to optimize for

Returns: Optimization recommendations including:

Specific improvement strategies
Priority-ranked optimization opportunities
Implementation guidance

Configuration Reference

The GitBook MCP server supports multiple configuration methods with the following precedence (highest to lowest):

CLI Arguments - Passed when starting the MCP server
Configuration Files - Embedded in project configuration files
Environment Variables - Set in .env.local or system environment

Environment Variables

Variable	Required	Type	Description
`GITBOOK_API_TOKEN`	Yes	string	GitBook API token (obtain from https://app.gitbook.com/account/developer)
`GITBOOK_ORGANIZATION_ID`	No	string	Default organization ID for operations
`GITBOOK_SPACE_ID`	No	string	Default space ID for single-space projects

Note: Environment variables can be set in .env.local, .env, or your system environment.

CLI Arguments

Argument	Alias	Type	Description
`--organization-id`	`--org`	string	Organization ID to work with
`--space-id`	`--space`	string	Default space for operations

Example:

node dist/index.js --organization-id your-org-id --space-id your-space-id

Additional Configuration Files

Typically these files are provided as context to the AI assistant, which means you can store project-based configuration.

.github/copilot-instructions.md
.cursorrules
.cursor/rules/rules.md
.cursor/rules/instructions.md

e.g.

Format:

## GitBook Configuration

For GitBook MCP operations, use the following configuration:

- organization-id: your-org-id-here
- space-id: your-space-id-here

Default Parameter Behavior

When GITBOOK_ORGANIZATION_ID or GITBOOK_SPACE_ID are configured:

Tools marked as "optional" can omit the corresponding ID parameters
The configured default values will be used automatically
Explicit parameters in tool calls override defaults

Development

Prerequisites

Node.js 20+
npm
GitBook API token (obtain from https://app.gitbook.com/account/developer)

Installation & Setup

git clone https://github.com/rickysullivan/gitbook-mcp.git
cd gitbook-mcp
npm install
npm run setup
# Add your GITBOOK_API_TOKEN to .env.local (for local development only)

Development

npm run dev

Debugging

DEBUG=1 npm run dev

Add the MCP to VS Code for development

You will need to use node as the command when running locally. The first arg should be the path to the compiled JavaScript output (e.g., dist/index.js).

{
    "servers": {
        "gitbook-mcp-dev": {
            "type": "stdio",
            "command": "node",
            "args": [
                "/my/path/to/gitbook-mcp/dist/index.js",
                "--organization-id=Luj2l6y6cIUPXJwbC574"
            ],
            "env": {
                "GITBOOK_API_TOKEN": "gb_api_UHEGTNsMg0ONPTnm0LpsJNBCCikQyOMkBTtZNDAB"
            }
        }
    }
}

Testing

There are currently no unit or integration tests; running npm run test only checks that the TypeScript code compiles successfully (type-check/build verification), and does not execute any actual tests.

npm run test

Error Handling

Common Error Codes

Error Code	Description	Resolution
`401`	Unauthorized - Invalid API token	Verify `GITBOOK_API_TOKEN` is correct
`403`	Forbidden - Insufficient permissions	Check space/organization access permissions
`404`	Not Found - Resource doesn't exist	Verify space/page/collection IDs are correct
`429`	Rate Limited - Too many requests	Implement request throttling
`500`	Internal Server Error	Check server logs for detailed error information

Troubleshooting

Token Issues:

Ensure token starts with gb_live_
Verify token has not expired
Check token permissions in GitBook settings

ID Resolution:

Use list_organizations to find valid organization IDs
Use list_spaces to find valid space IDs
Use get_space_content to find valid page IDs

Configuration Issues:

Verify environment variables are properly set
Check file permissions on configuration files
Ensure CLI arguments are properly formatted

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License - see the LICENSE file for details.

Disclaimer

This project is independently developed and is not officially affiliated with, endorsed by, or sponsored by GitBook.

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.github		.github
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
PROMPTS.md		PROMPTS.md
README.md		README.md
gitbook-mcp.code-workspace		gitbook-mcp.code-workspace
openapi.json		openapi.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

rickysullivan/gitbook-mcp

Folders and files

Latest commit

History

Repository files navigation

GitBook MCP Server Reference

Overview

Quick Setup

Prerequisites

IDE and AI Assistant Integration

VS Code (with GitHub Copilot)

Claude Desktop

GitHub Copilot plugin for JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.):

JetBrains AI Assistant

Getting Your GitBook Credentials

Configuration Options

API Reference

Tools

Organization Discovery

List Organizations (list_organizations) 📖 🔄 🌐

Space Management

List Spaces (list_spaces) 📖 🔄 🌐

Get Space Details (get_space) 📖 🔄 🌐

Get Space Content (get_space_content) 📖 🔄 🌐

Search Content (search_content) 📖 🔄 🌐

Content Retrieval

Get Page Content (get_page_content) 📖 🔄 🌐

Get Page by Path (get_page_by_path) 📖 🔄 🌐

File Management

Get Space Files (get_space_files) 📖 🔄 🌐

Get File Details (get_file) 📖 🔄 🌐

Collection Management

List Collections (list_collections) 📖 🔄 🌐

Get Collection Details (get_collection) 📖 🔄 🌐

Get Collection Spaces (get_collection_spaces) 📖 🔄 🌐

Prompts

Fetch Documentation (fetch_documentation)

Analyze Content Gaps (analyze_content_gaps)

Content Audit (content_audit)

Documentation Summary (documentation_summary)

Content Optimization (content_optimization)

Configuration Reference

Environment Variables

CLI Arguments

Additional Configuration Files

Default Parameter Behavior

Development

Prerequisites

Installation & Setup

Development

Debugging

Add the MCP to VS Code for development

Testing

Error Handling

Common Error Codes

Troubleshooting

Contributing

License

Related Documentation

Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Contributors 3

Uh oh!

Languages

List Organizations (`list_organizations`) 📖 🔄 🌐

List Spaces (`list_spaces`) 📖 🔄 🌐

Get Space Details (`get_space`) 📖 🔄 🌐

Get Space Content (`get_space_content`) 📖 🔄 🌐

Search Content (`search_content`) 📖 🔄 🌐

Get Page Content (`get_page_content`) 📖 🔄 🌐

Get Page by Path (`get_page_by_path`) 📖 🔄 🌐

Get Space Files (`get_space_files`) 📖 🔄 🌐

Get File Details (`get_file`) 📖 🔄 🌐

List Collections (`list_collections`) 📖 🔄 🌐

Get Collection Details (`get_collection`) 📖 🔄 🌐

Get Collection Spaces (`get_collection_spaces`) 📖 🔄 🌐

Fetch Documentation (`fetch_documentation`)

Analyze Content Gaps (`analyze_content_gaps`)

Content Audit (`content_audit`)

Documentation Summary (`documentation_summary`)

Content Optimization (`content_optimization`)

Packages