GitBook MCP Server

# 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: ```json { "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): ```json { "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): ```json { "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](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) 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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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 | 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:** ```bash 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:** ```markdown ## 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 ```bash 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 ```bash npm run dev ``` ### Debugging ```bash 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`). ```json { "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. ```bash 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 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request ## License MIT License - see the [LICENSE](LICENSE) file for details. ## Related Documentation - [GitBook API Documentation](https://api.gitbook.com/openapi.json) - [Model Context Protocol Specification](https://modelcontextprotocol.io) - [Detailed Prompt Documentation](./PROMPTS.md) ## Disclaimer This project is independently developed and is not officially affiliated with, endorsed by, or sponsored by [GitBook](https://www.gitbook.com).