GitBook MCP Server

GitBook

GitBook is a documentation platform where teams create, review, and publish structured content. It combines a WYSIWYG editor with Git-like version control (change requests, revisions, merges).

Data Model & Hierarchy

• User — A user account. Has id, displayName, email, photoURL. A user can belong to multiple organizations.
• Organization — Top-level container that owns all resources. Has id, title, plan, URLs. All spaces, collections, teams, and members live under an org.
• Space — A documentation project (like a repo). Spaces hold pages, files, change requests, and revisions. Each space has visibility (public/private), optional Git sync, and its own permission set. Spaces can belong to a collection or be standalone within an org.
• Collection — A folder that groups related spaces within an organization. Collections can be nested. Useful for organizing many documentation projects by product or team.
• Page — A content unit within a space. Pages are hierarchical (parent/child via groups). Each page has id, title, path (URL slug), kind (document/group/link), and an optional document body. Pages exist in the current revision or within a change request.
• Change Request — A branch-like construct for proposing edits. Has a status lifecycle: draft → open → merged/closed. Supports reviews, comments, and per-page diffs. Similar concept to a pull request.
• Revision — An immutable snapshot of space content at a point in time. Every merge creates a new revision.
• Team — A named group of org members used for permission assignment on spaces and collections.
• Member — A user's membership in an organization, including their role (admin, member, guest, reader, etc.) and activity timestamps.
• Comment — Threaded discussion on a space or change request, optionally attached to a specific page. Supports replies and has open/resolved status.
• File — Media/asset attached to a space (images, PDFs). Has contentType, downloadURL, and size.

Entity Relationships

Organization ─┬─ Spaces (many) ├─ Collections ── Spaces (grouped) ├─ Members (users + roles) └─ Teams ── Members (grouped for permissions)

Space ─┬─ Content (revision tree of pages) ├─ Pages (hierarchical documents) ├─ Change Requests (branch-like edits) ├─ Revisions (immutable snapshots) ├─ Comments (inline discussion, threaded with replies) ├─ Files (attached media/assets) └─ Permissions (user + team access levels)

Key Workflows

1. Discover structure: Get orgs → list spaces per org → list collections → explore content tree per space.
2. Read content: Get content tree for page hierarchy, then fetch individual pages for document body. List files for attached assets.
3. Search: Search across all org spaces or within a single space by keyword.
4. Review changes: List open change requests → inspect individual CR details → read comments and diffs.
5. Audit access: List org members with roles → list teams and team members → get space permissions.
6. Propose edits: Create a change request → update its status to open → merge when ready.
7. Collaborate: Post comments on spaces or change requests → reply to existing comment threads.
8. Inspect history: Get revisions to see historical content snapshots and diffs between versions.

Gotchas

• Space-first scoping: Content, change requests, revisions, comments, files, permissions, and search within a space all need space_id.
• Org-first for discovery: Spaces, collections, members, teams, and org-wide search need organization_id.
• Page paths are URL slugs: e.g. 'getting-started/quickstart'. Use page_path for human-readable lookups, page_id for precise access.
• Content tree vs flat list: GET content returns hierarchical tree; use list_pages=true for a flat enumeration.
• Change request status: Defaults to 'open'; pass status='merged' or 'closed' to see historical CRs.
• Change request lifecycle: draft → open → merged (via merge endpoint) or archived (via status update). Cannot merge a draft — must open it first.
• Comments use markdown: When creating comments, the body accepts markdown format which is auto-converted to GitBook's document structure.
• Revision IDs: Found in space details (revision field) and change request objects (revision, revisionInitial). Use these to inspect specific snapshots.
• Pagination: Uses cursor-based pagination — responses include a 'next' cursor when more results exist.