Connect an AI assistant to your BookStack wiki through the Model Context Protocol. Search documentation, answer questions with source links, summarize books, and optionally maintain pages and other content.
Read-only by default. The server exposes 21 read tools and, when enabled, 22 write tools. BookStack permissions still apply to every API request. Use a dedicated account with access to only the content the assistant should see.
In BookStack, open your profile's API Tokens section and create a token for a dedicated user. Its role needs Access System API and permission to view the relevant books/pages. Copy both the Token ID and Token Secret; they are separate values.
Also grant Export Content to read WYSIWYG pages as Markdown: BookStack stores no Markdown source for those pages, so the server uses its export endpoint as a fallback. User lookup and recycle-bin tools require additional administrative permissions; ordinary reading does not.
| Your setup | Start here |
|---|---|
| Claude Desktop | Install the .mcpb bundle from the latest release under Settings → Extensions, then enter the three BookStack settings |
| Claude Code | Marketplace or direct CLI setup |
| Codex or Gemini CLI | Native plugin and extension setup |
| Cursor | Native plugin or manual MCP setup |
| Any local MCP client | Use the stdio configuration below |
| LibreChat / shared Docker service | Internal HTTP deployment |
| Remote connector with Microsoft sign-in | HTTPS and Entra OAuth deployment |
For npm-based installations, use a supported Node.js LTS release (Node 24 recommended; CI also uses Node 22). The published package declares node >=18; that minimum is not a recommendation to run an unsupported Node release. Docker includes its own Node runtime.
Add this entry to your client's MCP configuration, replacing the example values:
{
"mcpServers": {
"bookstack": {
"command": "npx",
"args": ["-y", "bookstack-mcp@5.7.1"],
"env": {
"BOOKSTACK_BASE_URL": "https://wiki.example.com",
"BOOKSTACK_TOKEN_ID": "your-token-id",
"BOOKSTACK_TOKEN_SECRET": "your-token-secret"
}
}
}
}This configuration contains credentials: keep it private and outside version control. It pins the reviewed release 5.7.1; update the exact version deliberately when upgrading. The repository's native plugin/extension launchers also pin a matching npm version.
Restart the client, check that BookStack tools appear, and ask: “List the books I can access, then find our onboarding guide and link to it.” This verifies MCP connectivity and BookStack access. Starting npx without the required settings fails; starting it in a terminal with settings waits for MCP input rather than opening a web interface.
The client guide covers Claude Desktop, Claude Code, Codex, Cursor, Gemini CLI, and LibreChat, including per-user HTTP credential headers. The configuration reference documents all server settings and the different npm and Docker defaults.
For development from a checkout, see CONTRIBUTING.md. The server does not automatically read .env; use the client's env settings, export variables, or explicitly pass Node's --env-file option.
| Task | Tools and behavior |
|---|---|
| Find information | search_content, search_pages, find_users, get_recent_changes |
| Read the wiki | List/detail tools for books, chapters, pages, shelves, attachments, and comments; list_images |
| Export | export_page, export_book, export_chapter as HTML, Markdown, plaintext, PDF, or ZIP |
| Maintain content | Optional create/update/delete tools, gallery image uploads, and recycle-bin operations |
See the complete tool reference and recipes for all 43 tool names, pagination, tags, image policies, and version requirements. MCP tools/list on your connected server is authoritative for argument schemas and enabled tools.
To enable writes in non-OAuth mode, set BOOKSTACK_ENABLE_WRITE=true and use a BookStack token with the corresponding permissions. In OAuth mode, writes instead require the configured Entra role and a separate write-token pair. Entra users normally share those BookStack service accounts; sign-in does not automatically give each user their own BookStack identity or private content boundary.
- For HTML/WYSIWYG pages, read
get_pagewithformat: "raw"and update usinghtml. The renderedhtmlview can remove editor attributes and resolve includes. - For Markdown pages, read
format: "markdown"and update usingmarkdown. Savinghtmlclears the stored Markdown source. - Tags replace the entire tag list. Omit
tagsto preserve it, or send[]to clear it. Read the current list before changing individual tags. - Read all content chunks before replacing a large page. Worked examples show the workflow.
Clients with resource support can browse bookstack://book/{id} for book metadata and bookstack://page/{id} for Markdown and page metadata. Both templates provide ID completion through BookStack search.
Four MCP prompts guide read workflows: answer_from_wiki, find_pages, summarize_book, and recent_changes. Prompt arguments are documented alongside the tools. Client support for resources and prompts varies.
Use HTTPS, keep TLS verification enabled, and protect HTTP services with OAuth or a trusted internal network. HTTP without OAuth has no built-in caller authentication. Set an explicit allowed-host list when exposing a container; a host allowlist is not authentication.
HTTP image downloads require an allowed hostname, and local file uploads are disabled by default. Request bodies, request duration, and session counts are bounded. See deployment boundaries and the security policy, including private vulnerability reporting.
The privacy policy explains data flows, credentials, OAuth/Redis state, and logging. Your AI client and deployment operator may have additional policies. Use is governed by the terms and MIT license.
Browse the documentation index for installation, deployment, configuration, tool recipes, troubleshooting, contributions, releases, and HOL Guard. For a connection problem, start with the troubleshooting guide.
Design background: Why my BookStack MCP server starts read-only describes permission boundaries, shared-token rate limiting, and response-size decisions.