A Model Context Protocol (MCP) server that provides access to GitBook's API for AI assistants and LLM applications.
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.
- GitBook API token (obtain from https://app.gitbook.com/account/developer)
- Your GitBook Organization ID (optional but recommended)
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"
}
}
}
}
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.
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"
}
}
}
}
Add to your JetBrains AI Assistant MCP configuration (see official docs for the exact path):
- 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
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
.
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
Lists all accessible GitBook organizations.
Parameters: None
Returns:
{
"organizations": [
{
"id": "string",
"title": "string",
"urls": {
"app": "string",
"public": "string"
}
}
]
}
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"
}
}
]
}
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"
}
}
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"
}
]
}
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"
}
]
}
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 tofalse
) -
computed
(optional): Include computed revision data (boolean, defaults tofalse
)
Returns:
{
"id": "string",
"title": "string",
"content": "string",
"format": "string"
}
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"
}
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"
}
]
}
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"
}
Lists all accessible collections.
Parameters:
-
organizationId
(optional): Organization ID to filter collections
Returns:
{
"collections": [
{
"id": "string",
"title": "string",
"description": "string"
}
]
}
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"
}
Lists all spaces within a collection.
Parameters:
-
collectionId
(required): The ID of the collection
Returns:
{
"spaces": [
{
"id": "string",
"title": "string",
"visibility": "string"
}
]
}
The GitBook MCP server provides 6 AI-powered prompts for documentation workflows:
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
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
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
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
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
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
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.
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
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
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
- Node.js 20+
- npm
- GitBook API token (obtain from https://app.gitbook.com/account/developer)
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)
npm run dev
DEBUG=1 npm run dev
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"
}
}
}
}
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 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 |
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
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License - see the LICENSE file for details.
This project is independently developed and is not officially affiliated with, endorsed by, or sponsored by GitBook.