Gitbook MCP

GitBook MCP 服务参考

一种 Model Context Protocol（MCP）服务，可为 AI 助手和大模型应用提供对 GitBook API 的访问。

概述

GitBook MCP 服务通过标准化的 MCP 接口，支持以编程方式访问 GitBook 组织、空间、集合和内容。它提供 12 个用于内容操作的工具，以及 6 个面向文档工作流的 AI 驱动提示词。

快速设置

前置条件

• GitBook API 令牌（从 https://app.gitbook.com/account/developer 获取）
• GitBook 组织 ID（可选，但建议提供）

IDE 和 AI 助手集成

VS Code（搭配 GitHub Copilot）

在 VS Code 的 MCP 设置中添加：

{
    "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

在 Claude Desktop 配置中添加（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

详情请参阅 https://modelcontextprotocol.io/quickstart/user。

JetBrains IDE 的 GitHub Copilot 插件（IntelliJ IDEA、WebStorm 等）：

在 JetBrains IDE 的 GitHub Copilot MCP 设置中添加（路径可能因产品和操作系统而异，例如，Linux/macOS 上 IntelliJ 的路径为 ~/.config/github-copilot/intellij/mcp.json，其他 JetBrains IDE 和平台则使用相应目录）：

{
    "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

在 JetBrains AI Assistant 的 MCP 配置中添加（确切路径请参阅官方文档）：

获取 GitBook 凭据

1. API 令牌：访问 https://app.gitbook.com/account/developer 生成 API 令牌
2. 组织 ID：设置完成后，使用 list_organizations 工具查找组织 ID
3. 空间 ID（可选）：使用 list_spaces 工具（需要有效的组织 ID 和 API 令牌）查找特定空间 ID
4. 空间 ID（可选）：使用 list_spaces 工具查找特定空间 ID

配置选项

可以通过以下方式配置服务：

• CLI 参数：--organization-id、--space-id
• MCP 配置中的环境变量：通过 MCP 配置中的 env 对象设置
• 系统环境变量：GITBOOK_API_TOKEN、GITBOOK_ORGANIZATION_ID、GITBOOK_SPACE_ID

注意：.env 文件仅在本地运行服务进行开发时受支持，使用 npx gitbook-mcp 时不受支持。

API 参考

工具

GitBook MCP 服务提供 12 个按功能类别组织的工具。每个工具都包含行为提示：

• 📖 只读：工具仅读取数据，不会进行任何修改
• 🔄 幂等：使用相同参数重复调用不会产生额外影响，结果也相同
• 🌐 开放世界：工具会与外部实体交互

组织发现

列出组织（list_organizations）📖 🔄 🌐

列出所有可访问的 GitBook 组织。

**参数：**无

返回：

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

空间管理

列出空间（list_spaces）📖 🔄 🌐

列出空间，可按组织筛选。

参数：

• organizationId（可选）：用于筛选空间的组织 ID

返回：

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

获取空间详情（get_space）📖 🔄 🌐

获取特定空间的详细信息。

参数：

• spaceId（必需）：要获取的空间 ID

返回：

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

获取空间内容（get_space_content）📖 🔄 🌐

获取空间的内容结构和页面。

参数：

• spaceId（可选）：空间 ID（若已配置，则使用默认值）

返回：

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

搜索内容（search_content）📖 🔄 🌐

使用全文搜索在空间中搜索内容。

参数：

• query（必需）：搜索查询字符串
• spaceId（可选）：要搜索的空间 ID（若已配置，则使用默认值）

返回：

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

内容检索

获取页面内容（get_page_content）📖 🔄 🌐

获取特定页面的内容。

参数：

• pageId（必填）：要获取的页面 ID
• spaceId（可选）：包含该页面的空间 ID
• format（可选）：输出格式（"document" 或 "markdown"，默认为 "document"）
• metadata（可选）：包含修订元数据（布尔值，默认为 false）
• computed（可选）：包含计算后的修订数据（布尔值，默认为 false）

返回：

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

按路径获取页面（get_page_by_path）📖 🔄 🌐

使用页面路径获取页面内容。

参数：

• pagePath（必填）：要获取的页面路径
• spaceId（可选）：包含该页面的空间 ID

返回：

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

文件管理

获取空间文件（get_space_files）📖 🔄 🌐

列出空间中的所有文件。

参数：

• spaceId（可选）：空间 ID（如果已配置，则使用默认值）

返回：

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

获取文件详情（get_file）📖 🔄 🌐

获取特定文件的详情。

参数：

• fileId（必填）：要获取的文件 ID
• spaceId（可选）：包含该文件的空间 ID

返回：

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

集合管理

列出集合（list_collections）📖 🔄 🌐

列出所有可访问的集合。

参数：

• organizationId（可选）：用于筛选集合的组织 ID

返回：

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

获取集合详情（get_collection）📖 🔄 🌐

获取特定集合的详情。

参数：

• collectionId（必填）：要获取的集合 ID

返回：

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

获取集合空间（get_collection_spaces）📖 🔄 🌐

列出集合中的所有空间。

参数：

• collectionId（必填）：集合 ID

返回：

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

提示词

GitBook MCP 服务为文档工作流提供 6 个 AI 驱动的提示词：

获取文档（fetch_documentation）

获取并分析特定主题的 GitBook 文档内容。

参数：

• topic（必填）：要搜索和分析的主题或内容
• spaceId（可选）：要搜索的空间 ID（如果已配置，则使用默认值）
• includeStructure（可选）：设为 "true" 以包含空间结构

返回： 对指定主题相关文档的全面分析，包括：

• 相关页面和章节
• 内容摘要
• 缺失内容或需要改进的部分

分析内容缺口（analyze_content_gaps）

识别文档中的内容缺口和缺失内容。

参数：

• spaceId（可选）：要分析的空间 ID（如果已配置，则使用默认值）
• comparisonSource（可选）：用于比较的来源（默认值："internal analysis"）

返回： 详细的缺口分析，包括：

• 缺失的主题和未完成的章节
• 按重要性排序的覆盖缺口
• 新内容主题的建议

内容审查（content_audit）

对文档内容进行质量审查。

参数：

• spaceId（可选）：要审查的空间 ID（如果已配置，则使用默认值）
• auditCriteria（可选）：具体的审查标准（默认值："general quality and consistency"）

返回： 全面的质量评估，包括：

• 内容质量和一致性审查
• 过时信息识别
• 写作风格和格式建议

文档摘要（documentation_summary）

生成 GitBook 空间的全面摘要。

参数：

• spaceId（可选）：要生成摘要的空间 ID（如果已配置，则使用默认值）
• summaryType（可选）：摘要类型——"overview"、"technical"、"user-guide" 或 "custom"（默认值："overview"）

返回： 结构化摘要，包括：

• 空间结构和内容组织
• 主要主题和核心内容
• 目标受众和使用场景

内容优化（content_optimization）

针对 SEO、可读性、结构或性能优化内容。

参数：

• spaceId（可选）：要优化的空间 ID（如果已配置，则使用默认值）
• optimizationType（必填）：优化类型——“SEO”、“readability”、“structure”或“performance”
• targetMetrics（可选）：要优化的具体指标或目标

返回： 优化建议，包括：

• 具体的改进策略
• 按优先级排序的优化机会
• 实施指导

配置参考

GitBook MCP 服务支持多种配置方式，优先级如下（从高到低）：

1. CLI 参数——启动 MCP 服务时传入
2. 配置文件——嵌入项目配置文件中
3. 环境变量——在 .env.local 或系统环境中设置

环境变量

变量	必填	类型	描述
GITBOOK_API_TOKEN	是	string	GitBook API token（从 https://app.gitbook.com/account/developer 获取）
GITBOOK_ORGANIZATION_ID	否	string	操作的默认组织 ID
GITBOOK_SPACE_ID	否	string	单空间项目的默认空间 ID

注意： 环境变量可以在 .env.local、.env 或系统环境中设置。

CLI 参数

参数	别名	类型	描述
--organization-id	--org	string	要操作的组织 ID
--space-id	--space	string	操作的默认空间

示例：

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

其他配置文件

通常会将这些文件作为上下文提供给 AI 助手，这意味着你可以存储基于项目的配置。

1. .github/copilot-instructions.md
2. .cursorrules
3. .cursor/rules/rules.md
4. .cursor/rules/instructions.md

例如：

格式：

## GitBook Configuration

For GitBook MCP operations, use the following configuration:

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

默认参数行为

配置了 GITBOOK_ORGANIZATION_ID 或 GITBOOK_SPACE_ID 时：

• 标记为“可选”的工具可以省略相应的 ID 参数
• 系统会自动使用已配置的默认值
• 工具调用中的显式参数会覆盖默认值

开发

前置条件

• Node.js 20+
• npm
• GitBook API token（从 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

在 VS Code 中添加 MCP 以进行开发

在本地运行时，需要将 node 用作命令。 第一个参数应为已编译 JavaScript 输出文件的路径（例如，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"
            }
        }
    }
}

测试

目前没有单元测试或集成测试；运行 npm run test 只会检查 TypeScript 代码是否成功编译（类型检查／构建验证），不会执行任何实际测试。

npm run test

错误处理

常见错误代码

错误代码	描述	解决方法
401	未授权 - API 令牌无效	确认 GITBOOK_API_TOKEN 正确
403	禁止访问 - 权限不足	检查空间/组织的访问权限
404	未找到 - 资源不存在	确认空间/页面/集合 ID 正确
429	请求过多 - 请求频率受限	实施请求节流
500	服务器内部错误	查看服务器日志以获取详细错误信息

故障排除

令牌问题：

• 确保令牌以 gb_live_ 开头
• 确认令牌尚未过期
• 在 GitBook 设置中检查令牌权限

ID 查询：

• 使用 list_organizations 查找有效的组织 ID
• 使用 list_spaces 查找有效的空间 ID
• 使用 get_space_content 查找有效的页面 ID

配置问题：

• 确认环境变量已正确设置
• 检查配置文件的文件权限
• 确保 CLI 参数格式正确

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交 pull request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

相关文档

• GitBook API 文档
• Model Context Protocol 规范
• 提示词详细文档

免责声明

本项目由独立开发，与 GitBook 没有官方关联，也未获得其认可或赞助。