BookStack MCP Server
A Model Context Protocol (MCP) server that gives AI assistants full access to your BookStack documentation — search, read, create, and manage content.
npx bookstack-mcp
Read the privacy policy for data flows, credentials, optional OAuth/Redis state, and logging. Your MCP client and deployment operator may have additional policies. The terms of use explain the scope of the software under its MIT license.
Field notes: Why my BookStack MCP server starts read-only covers the shared-token rate-limit failure, process-wide cache, response-size measurements, and permission boundaries that shaped the current design.
Features
- 21 read-only tools + 22 write tools for BookStack API access
- Books, chapters, pages, shelves, attachments, and comments — full CRUD
- Recycle bin support — restore or permanently delete soft-deleted content
- Type-safe input validation with Zod (auto-coerces string/number params for broad client compatibility)
- Embedded URLs and content previews in all responses
- Markdown export fallback for HTML-authored pages, so AI clients always get usable content
- Token-efficient responses: compact JSON, no redundant fields, no N+1 fetches — ~30–55% smaller payloads than 3.x
- Write operations disabled by default for safety
- Works with Claude Desktop, Claude Code, LibreChat, and any MCP-compatible client
- Stdio and Streamable HTTP transports
Quick Start
Install from npm
npx bookstack-mcp
Or clone and build
git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
npm install && npm run build
npm start
Environment Variables
BOOKSTACK_BASE_URL=https://your-bookstack.com # Required
BOOKSTACK_TOKEN_ID=your-token-id # Required
BOOKSTACK_TOKEN_SECRET=your-token-secret # Required
BOOKSTACK_ENABLE_WRITE=false # Optional, default false
BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false # Optional, default false
BOOKSTACK_TIMEOUT_MS=30000 # Optional, timeout per HTTP attempt
BOOKSTACK_RETRY_TIMEOUT_MS=60000 # Optional, total budget per API request
Each API request has a total budget covering concurrency queue time, HTTP attempts, and rate-limit backoff. HTTP 429 responses are retried up to five times, with each delay capped at 30 seconds. If a delay cannot fit in the remaining budget or retries are exhausted, the tool returns an explicit BookStack rate-limit error. The budget applies to each API request; tools that fetch multiple endpoints can take longer.
With write operations enabled, update_page and update_chapter accept priority
as a non-negative integer (including numeric strings). Lower values sort first;
use these tools to order pages and chapters within a book.
create_page and update_page also accept an optional changelog message
(1–180 characters), saved as the revision summary in the page's history. It
needs BookStack v26.09 or newer; older versions silently ignore it.
get_page accepts format: "raw" to return the page's stored editor HTML
(BookStack's raw_html). The html format is the rendered view readers see:
page includes are resolved and the content filter has run, so attributes such as
rel, data-* or legacy width/align may be gone.
When you edit a page, match the format to the page's editor field:
- HTML (WYSIWYG) pages: read
format: "raw"and send the result back asupdate_page.html. Starting fromhtmlsaves the rendered output and drops whatever rendering removed. - Markdown pages: read
format: "markdown"and send the result back asupdate_page.markdown. For these pagesraw_htmlis HTML generated from the Markdown, and saving anyhtmlclears the stored Markdown source.
Security warning:
BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=truedisables TLS certificate verification for outgoing requests to BookStack. Use only for self-signed certs on a trusted LAN — connections become vulnerable to MITM attacks. The server logs aWARNINGline at startup whenever this is enabled.
Client Configuration
Codex plugin
This repository includes a native Codex manifest at
.codex-plugin/plugin.json, which references the stdio server in .mcp.json.
Set BOOKSTACK_BASE_URL, BOOKSTACK_TOKEN_ID, and BOOKSTACK_TOKEN_SECRET in
the environment that launches Codex before enabling the plugin. Write operations
remain disabled unless BOOKSTACK_ENABLE_WRITE=true is set.
The manifest supplies the project website, privacy policy, and terms of use for plugin directories, including HOL. The HOL Guard CI workflow scans this manifest alongside the Claude and Gemini manifests; it does not submit or publish listings.
Claude Desktop
The easiest install is the prebuilt MCPB bundle attached to each GitHub release:
- Download
bookstack-mcp-<version>.mcpbfrom the latest release. - Open Claude Desktop → Settings → Extensions and drag the
.mcpbfile in (or click Install Extension). - Fill in BookStack URL, API Token ID, and API Token Secret. Tokens are stored in your OS keychain. Leave Enable Write Operations as
falsefor read-only access; set totrueto enable create/update/delete tools.
Manual install (JSON config)
If you'd rather edit the config file directly:
{
"mcpServers": {
"bookstack": {
"command": "npx",
"args": ["-y", "bookstack-mcp"],
"env": {
"BOOKSTACK_BASE_URL": "https://your-bookstack.com",
"BOOKSTACK_TOKEN_ID": "your-token-id",
"BOOKSTACK_TOKEN_SECRET": "your-token-secret"
}
}
}
}
LibreChat (stdio, single-user)
Add to your librechat.yaml:
mcpServers:
bookstack:
command: npx
args:
- -y
- bookstack-mcp
env:
BOOKSTACK_BASE_URL: "https://your-bookstack.com"
BOOKSTACK_TOKEN_ID: "your-token-id"
BOOKSTACK_TOKEN_SECRET: "your-token-secret"
LibreChat (Streamable HTTP, recommended for production / Docker)
Run the server as a long-lived HTTP service and point LibreChat at the URL. This is the right setup for multi-user or containerized deployments.
Start the server in HTTP mode:
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
BOOKSTACK_BASE_URL=https://your-bookstack.com \
BOOKSTACK_TOKEN_ID=your-token-id \
BOOKSTACK_TOKEN_SECRET=your-token-secret \
npx bookstack-mcp
Then configure LibreChat:
mcpServers:
bookstack:
type: streamable-http
url: http://bookstack-mcp:8080/mcp
Per-user BookStack credentials
Set BOOKSTACK_ALLOW_REQUEST_CREDENTIALS=true on the HTTP server to accept
X-Bookstack-Token-Id and X-Bookstack-Token-Secret on each request. Both headers
must be supplied together; when both are absent, the server uses its environment
credentials. This is opt-in and does not change the write-tool or OAuth role gates.
Use a read-only environment token with limited visibility for the fallback.
Credential overrides apply to each request, including reused MCP sessions, and
their slug caches are private to that request. Send credentials over HTTPS or a
trusted internal connection and configure proxies to redact these headers.
mcpServers:
bookstack:
type: streamable-http
url: http://bookstack-mcp:8080/mcp
headers:
X-Bookstack-Token-Id: "{{BOOKSTACK_TOKEN_ID}}"
X-Bookstack-Token-Secret: "{{BOOKSTACK_TOKEN_SECRET}}"
customUserVars:
BOOKSTACK_TOKEN_ID: { title: "BookStack token ID" }
BOOKSTACK_TOKEN_SECRET: { title: "BookStack token secret" }
Gallery images
list_images lists images with optional uploaded_to, offset, count, and
sort parameters. With write mode enabled, create_image accepts exactly one
absolute file_path or HTTP(S) url, a required existing page ID uploaded_to,
and an optional name. It uploads the binary data directly and returns BookStack's
hosted URL, thumbnails, and content.html / content.markdown snippets. PNG,
JPEG, GIF, WebP, and SVG sources up to 50 MB are supported; BookStack may impose
smaller limits. delete_image deletes an image and its thumbnails by id.
In stdio mode, files and HTTP(S) URLs are available to the trusted local client.
In HTTP mode, local files are disabled unless
BOOKSTACK_ALLOW_LOCAL_IMAGE_FILES=true. URL sources require a comma-separated
BOOKSTACK_IMAGE_ALLOWED_HOSTS hostname allowlist, which also applies to every
redirect. For example, allow your image service with
BOOKSTACK_IMAGE_ALLOWED_HOSTS=images.example.com. Source downloads never use
the BookStack authorization token. Deleting an image can break existing page references.
3.0.0 breaking change: the deprecated HTTP+SSE transport (
GET /sse+POST /messages) has been removed. Streamable HTTP at/mcpalready speaks SSE for streaming responses, and is the only HTTP transport in current MCP clients. If you're on an older client that needs the legacy endpoints, pin to[email protected].
HTTP transport environment variables
When binding to 0.0.0.0 (e.g. inside a container reachable from other services), set MCP_HTTP_ALLOWED_HOSTS to the hostnames LibreChat will use to reach this server, e.g. MCP_HTTP_ALLOWED_HOSTS=bookstack-mcp,bookstack-mcp.internal.
Restart LibreChat after config changes.
Remote hosting & Claude Connector (Docker + Entra OAuth)
A container image is published to ghcr.io/ttpears/bookstack-mcp (released :X.Y.Z/:latest,
plus per-PR preview tags :branch-<slug>). The server can run as a public Claude Connector
gated by Microsoft 365 / Entra ID login — users sign in, no API key or client credential to
paste; write tools are unlocked per session by an Entra app role.
See docs/SETUP.md for the full runbook: Entra app registration steps, the environment-variable reference, internal LibreChat deployment, and the public OAuth connector setup.
Claude Code (CLI)
The recommended path is the ttpears/claude-plugins marketplace, which ships this repo's plugin manifest (.claude-plugin/plugin.json):
/plugin marketplace add ttpears/claude-plugins
/plugin install bookstack-mcp@ttpears-plugins
Then set the BOOKSTACK_* environment variables in your shell so the plugin's MCP server can authenticate:
export BOOKSTACK_BASE_URL=https://your-bookstack.com
export BOOKSTACK_TOKEN_ID=your-token-id
export BOOKSTACK_TOKEN_SECRET=your-token-secret
Manual install (alternative)
If you'd rather not use the marketplace, register the server directly with claude mcp add. Repeat --env for each variable, put all flags before the server name, and use -- to mark the start of the command Claude Code will spawn:
claude mcp add bookstack \
--transport stdio \
--scope user \
--env BOOKSTACK_BASE_URL=https://your-bookstack.com \
--env BOOKSTACK_TOKEN_ID=your-token-id \
--env BOOKSTACK_TOKEN_SECRET=your-token-secret \
-- npx -y bookstack-mcp
Scope picks where the entry is written:
The resulting config entry looks like this (in .mcp.json for project scope, or ~/.claude.json otherwise):
{
"mcpServers": {
"bookstack": {
"type": "stdio",
"command": "npx",
"args": ["-y", "bookstack-mcp"],
"env": {
"BOOKSTACK_BASE_URL": "https://your-bookstack.com",
"BOOKSTACK_TOKEN_ID": "your-token-id",
"BOOKSTACK_TOKEN_SECRET": "your-token-secret"
}
}
}
}
Tip for committed
.mcp.json: Claude Code expands${VAR}and${VAR:-default}references in.mcp.jsonfrom the surrounding shell. Use that to keep secrets out of git: set"BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}"in the file and have each developer export the variable in their shell.
MCP Resources
Books and pages are also exposed as MCP resources, so clients that browse resources (Claude Desktop, MCP Inspector, etc.) can @-mention them directly:
Both templates support id autocompletion: as you type, the server searches BookStack and returns matching IDs so you don't have to remember numeric IDs by hand.
4.0.0 breaking changes: tool responses were trimmed for token efficiency. Removed fields:
direct_link,*_friendlydate strings,content_info,contextual_info,change_summary,pagination_hint,location,summary/tags_summary/book_counton shelves, and the buggypage_urlon attachments. Useurl, the ISO date fields, anddownload_urlinstead. Theget_capabilitiestool was removed — clients should usetools/list(built into MCP). Responses are now compact JSON (no pretty-printing) andget_recent_changesno longer issues per-result fetches.
Available Tools
Read Operations (always available)
Write Operations (requires BOOKSTACK_ENABLE_WRITE=true)
BookStack API Setup
- Log into BookStack as an admin
- Go to Settings > Users > Edit your user
- Ensure the user has Access System API permission
- In the API Tokens section, create a new token
- Copy the Token ID and Token Secret
Also grant the role “Export Content” if you read pages written in the WYSIWYG editor. BookStack returns an empty
markdownbody for those pages, andget_pagerecovers it from the server-side HTML→markdown export endpoint. Without the permission that fallback fails and the page reads as empty. The default Viewer role does not include it.
Security
- Write operations are disabled by default
- Use HTTPS for production instances
- Store API tokens securely (never commit to git)
- Consider a dedicated BookStack user with limited permissions
Development
npm run dev # Hot reload with tsx
npm run type-check # Type checking only
npm run build # Production build
License
MIT
