rickysullivan/gitbook-mcp

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

1. API Token: Visit https://app.gitbook.com/account/developer to generate your API token
2. Organization ID: Use the list_organizations tool after setup to find your organization ID
3. Space ID (optional): Use the list_spaces tool (requires a valid organization ID and API token) to find specific space IDs
4. 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):

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

Environment Variables

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

CLI Arguments

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.

1. .github/copilot-instructions.md
2. .cursorrules
3. .cursor/rules/rules.md
4. .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

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see the file for details.

Related Documentation

• GitBook API Documentation
• Model Context Protocol Specification

Disclaimer

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