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- 20 read-only tools + 18 write tools for complete BookStack API coverage
- 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
- Write operations disabled by default for safety
- Works with Claude Desktop, Claude Code, LibreChat, and any MCP-compatible client
- Stdio and Streamable HTTP transports
npx bookstack-mcpgit clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
npm install && npm run build
npm startBOOKSTACK_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 falseSecurity 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.
Add to your Claude Desktop config:
{
"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"
}
}
}
}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"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-mcpThen configure LibreChat:
mcpServers:
bookstack:
type: streamable-http
url: http://bookstack-mcp:8080/mcp3.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 tobookstack-mcp@2.x.
| Variable | Default | Description |
|---|---|---|
MCP_TRANSPORT |
stdio |
Set to http to enable the HTTP server |
MCP_HTTP_PORT |
8080 |
Port to listen on |
MCP_HTTP_HOST |
127.0.0.1 |
Bind address. Loopback by default for safety |
MCP_HTTP_ALLOWED_HOSTS |
(loopback only) | Comma-separated allowlist of Host header hostnames for DNS rebinding protection. Required when binding to a non-loopback address |
MCP_HTTP_PATH |
/mcp |
Streamable HTTP endpoint |
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.
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-secretIf 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-mcpScope picks where the entry is written:
| Scope | Where it lives | Shared via git | Use it when |
|---|---|---|---|
local (default) |
~/.claude.json, scoped to the current project |
No | Trying it out in one repo |
user |
~/.claude.json, available in every project |
No | You want bookstack everywhere |
project |
.mcp.json at the repo root |
Yes | The whole team should get it |
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.
Books and pages are also exposed as MCP resources, so clients that browse resources (Claude Desktop, MCP Inspector, etc.) can @-mention them directly:
| URI template | Description |
|---|---|
bookstack://book/{id} |
A book, returned as JSON metadata |
bookstack://page/{id} |
A page, returned as markdown plus a JSON metadata blob |
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.
| Tool | Description |
|---|---|
get_capabilities |
Server capabilities and configuration |
search_content |
Search across all content with filtering |
search_pages |
Search pages with optional book filtering |
get_books / get_book |
List or get details of books |
get_pages / get_page |
List or get full page content |
get_chapters / get_chapter |
List or get chapter details |
get_shelves / get_shelf |
List or get shelf details |
get_attachments / get_attachment |
List or get attachment details |
get_comments / get_comment |
List or get page comments (BookStack v25.11+) |
get_recycle_bin |
List items in the recycle bin |
export_page |
Export page as HTML, PDF, Markdown, plaintext, or ZIP |
export_book |
Export entire book |
export_chapter |
Export chapter |
get_recent_changes |
Recently updated content |
| Tool | Description |
|---|---|
create_book / delete_book |
Create or delete a book |
create_chapter / delete_chapter |
Create or delete a chapter |
create_page |
Create a new page (HTML or Markdown) |
update_page |
Update content, rename, or move to a different book/chapter |
delete_page |
Delete a page (recoverable from recycle bin) |
create_shelf / update_shelf / delete_shelf |
Manage shelves |
create_attachment / update_attachment / delete_attachment |
Manage attachments |
create_comment / update_comment / delete_comment |
Manage page comments (v25.11+) |
restore_deleted / permanently_delete |
Restore or permanently destroy items in the recycle bin |
- 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
- 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
npm run dev # Hot reload with tsx
npm run type-check # Type checking only
npm run build # Production buildMIT