Skip to content
Back to search

bookstack-mcp-server

A Model Context Protocol (MCP) server providing full access to BookStack's knowledge management capabilities

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pnocera--bookstack-mcp-server/badge.svg)](/listings/pnocera--bookstack-mcp-server)

HTML

<a href="/listings/pnocera--bookstack-mcp-server"><img src="/api/listings/pnocera--bookstack-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> ⚠️ **Requires [Bun](https://bun.sh) 1.1.0 or newer. Node.js is not supported.** > This package ships TypeScript source rather than a compiled bundle, and its > executable starts with `#!/usr/bin/env bun` — Bun must be installed on the > machine that runs it. `npx`/`npm install -g` will not work.

Configure first — the default HTTP transport **refuses to start** until both tokens below are set:

# 1. Configure
export BOOKSTACK_BASE_URL="https://your-bookstack.com/api"
export BOOKSTACK_API_TOKEN="token_id:token_secret"   # OUTBOUND: the credential this server spends
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"      # INBOUND: who may make it spend that credential

# 2. Run without installing (starts the HTTP server on port 3000)
bunx bookstack-mcp-server

# Or install globally, then run it by name
bun add -g bookstack-mcp-server
bookstack-mcp-server

The two tokens are **not** interchangeable and must not be set to the same value: `BOOKSTACK_API_TOKEN` is what the server presents to BookStack; `MCP_AUTH_TOKEN` is what callers must present to `POST /message`, which dispatches all 59 tools with the authority of the BookStack account behind `BOOKSTACK_API_TOKEN`. Skip `MCP_AUTH_TOKEN` only for [stdio](#-transports), which has no network surface and ignores it.

**Check it started:**

curl http://localhost:3000/          # => {"status":"running", ...}
curl -i http://localhost:3000/health # => 200 healthy, or 503 if BookStack is unreachable

Add to Claude

To use with Claude Desktop (requires Stdio mode):

# For Claude Code
claude mcp add bookstack bunx bookstack-mcp-server \
  --env BOOKSTACK_BASE_URL=https://your-bookstack.com/api \
  --env BOOKSTACK_API_TOKEN=token_id:token_secret \
  --env MCP_TRANSPORT=stdio

Configuration

Set these environment variables:

export BOOKSTACK_BASE_URL="https://your-bookstack.com/api"
export BOOKSTACK_API_TOKEN="token_id:token_secret"

# Required for the HTTP transport (the default); ignored by stdio.
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"

# Optional: transport mode — "http" (default) or "stdio"
export MCP_TRANSPORT="http"

> 💡 **Token Format**: Combine your BookStack Token ID and Token Secret as `token_id:token_secret`

Environment variables

| Variable | Default | Description | | --- | --- | --- | | `MCP_TRANSPORT` | `http` | Transport mode. Only the exact value `stdio` selects stdio; **any other value (or unset) starts the HTTP server**. | | `MCP_AUTH_TOKEN` | _(none — **required** for HTTP)_ | **Inbound** secret callers must present as `Authorization: Bearer <value>` on `POST /message`. The HTTP transport **refuses to start** without it — there is no "no auth" mode. Unrelated to `BOOKSTACK_API_TOKEN`, and must not be the same value. Ignored in stdio mode. Generate with `openssl rand -hex 32`. | | `BOOKSTACK_BASE_URL` | `http://localhost:8080/api` | Full URL to the BookStack API. Must be a valid URL and include the `/api` suffix. | | `BOOKSTACK_API_TOKEN` | _(none — required)_ | **Outbound** BookStack API token as `token_id:token_secret`. This is the credential the server spends on every tool call. Startup fails if unset. | | `BOOKSTACK_TIMEOUT` | `30000` | BookStack request timeout in milliseconds. | | `SERVER_PORT` | `3000` | Port the HTTP transport listens on. Ignored in stdio mode. | | `HTTP_BODY_LIMIT` | `73400320` (70 MiB) | Maximum accepted `POST /message` body, in bytes. Sized for the largest inline base64 upload the image/attachment tools advertise (50,000 KB). Express's own default is ~100 KB, which would reject real uploads with a `413`. Lower it if untrusted callers can reach the port. | | `SERVER_NAME` | `bookstack-mcp-server` | Server name reported over MCP and by `GET /`. | | `SERVER_VERSION` | the package's own version | Version reported over MCP `initialize`, by `GET /`, and by `bookstack_server_info`. Defaults to `package.json#version`; leave it unset unless you deliberately want a different value. |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 469 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # BookStack MCP Server
  2. Connect BookStack to Claude and other AI assistants through the Model Context Protocol (MCP). This server exposes 59 tools and 11 resources covering the supported subset of the BookStack API — books, pages, chapters, shelves, search, users, roles, permissions, attachments, images, the recycle bin, the audit log and system info.
  3. This server supports two transport modes: **Streamable HTTP** (default) and **Stdio**.
  4. - **Streamable HTTP (default)**: A stateless HTTP transport. Authentication parameters can be overridden per-request using HTTP headers (`x-bookstack-url` and `x-bookstack-token`).
  5. - **Stdio Mode**: Standard input/output for local integration (e.g., with Claude Desktop). Set `MCP_TRANSPORT=stdio` to enable.
  6. > ⚠️ **Looking for the HTTP endpoint?** The MCP endpoint is `POST /message` — not `/`.
  7. > See [Transports](#-transports) and [HTTP endpoints](#http-endpoints) below.
  8. ## ✨ What You Get
  9. - **BookStack Integration** - Access your books, pages, chapters, and content
  10. - **59 MCP Tools & 11 Resources** - CRUD, search and export across the supported endpoint families
  11. - **Search & Export** - Find content and export in multiple formats
  12. - **User Management** - Handle users, roles, and permissions
  13. - **Production Ready** - Rate limiting, validation, error handling, and logging
  14. ## 🚀 Quick Start
  15. > ⚠️ **Requires [Bun](https://bun.sh) 1.1.0 or newer. Node.js is not supported.**
  16. > This package ships TypeScript source rather than a compiled bundle, and its
  17. > executable starts with `#!/usr/bin/env bun` — Bun must be installed on the
  18. > machine that runs it. `npx`/`npm install -g` will not work.
  19. Configure first — the default HTTP transport **refuses to start** until both tokens
  20. below are set:
  21. ```bash
  22. # 1. Configure
  23. export BOOKSTACK_BASE_URL="https://your-bookstack.com/api"
  24. export BOOKSTACK_API_TOKEN="token_id:token_secret" # OUTBOUND: the credential this server spends
  25. export MCP_AUTH_TOKEN="$(openssl rand -hex 32)" # INBOUND: who may make it spend that credential
  26. # 2. Run without installing (starts the HTTP server on port 3000)
  27. bunx bookstack-mcp-server
  28. # Or install globally, then run it by name
  29. bun add -g bookstack-mcp-server
  30. bookstack-mcp-server
  31. ```
  32. The two tokens are **not** interchangeable and must not be set to the same value:
  33. `BOOKSTACK_API_TOKEN` is what the server presents to BookStack; `MCP_AUTH_TOKEN` is
  34. what callers must present to `POST /message`, which dispatches all 59 tools with the
  35. authority of the BookStack account behind `BOOKSTACK_API_TOKEN`. Skip `MCP_AUTH_TOKEN`
  36. only for [stdio](#-transports), which has no network surface and ignores it.
  37. **Check it started:**
  38. ```bash
  39. curl http://localhost:3000/ # => {"status":"running", ...}
  40. curl -i http://localhost:3000/health # => 200 healthy, or 503 if BookStack is unreachable
  41. ```
  42. ### Add to Claude
  43. To use with Claude Desktop (requires Stdio mode):
  44. ```bash
  45. # For Claude Code
  46. claude mcp add bookstack bunx bookstack-mcp-server \
  47. --env BOOKSTACK_BASE_URL=https://your-bookstack.com/api \
  48. --env BOOKSTACK_API_TOKEN=token_id:token_secret \
  49. --env MCP_TRANSPORT=stdio
  50. ```
  51. ### Configuration
  52. Set these environment variables:
  53. ```bash
  54. export BOOKSTACK_BASE_URL="https://your-bookstack.com/api"
  55. export BOOKSTACK_API_TOKEN="token_id:token_secret"
  56. # Required for the HTTP transport (the default); ignored by stdio.
  57. export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
  58. # Optional: transport mode — "http" (default) or "stdio"
  59. export MCP_TRANSPORT="http"
  60. ```
  61. > 💡 **Token Format**: Combine your BookStack Token ID and Token Secret as `token_id:token_secret`
  62. #### Environment variables
  63. | Variable | Default | Description |
  64. | --- | --- | --- |
  65. | `MCP_TRANSPORT` | `http` | Transport mode. Only the exact value `stdio` selects stdio; **any other value (or unset) starts the HTTP server**. |
  66. | `MCP_AUTH_TOKEN` | _(none — **required** for HTTP)_ | **Inbound** secret callers must present as `Authorization: Bearer <value>` on `POST /message`. The HTTP transport **refuses to start** without it — there is no "no auth" mode. Unrelated to `BOOKSTACK_API_TOKEN`, and must not be the same value. Ignored in stdio mode. Generate with `openssl rand -hex 32`. |
  67. | `BOOKSTACK_BASE_URL` | `http://localhost:8080/api` | Full URL to the BookStack API. Must be a valid URL and include the `/api` suffix. |
  68. | `BOOKSTACK_API_TOKEN` | _(none — required)_ | **Outbound** BookStack API token as `token_id:token_secret`. This is the credential the server spends on every tool call. Startup fails if unset. |
  69. | `BOOKSTACK_TIMEOUT` | `30000` | BookStack request timeout in milliseconds. |
  70. | `SERVER_PORT` | `3000` | Port the HTTP transport listens on. Ignored in stdio mode. |
  71. | `HTTP_BODY_LIMIT` | `73400320` (70 MiB) | Maximum accepted `POST /message` body, in bytes. Sized for the largest inline base64 upload the image/attachment tools advertise (50,000 KB). Express's own default is ~100 KB, which would reject real uploads with a `413`. Lower it if untrusted callers can reach the port. |
  72. | `SERVER_NAME` | `bookstack-mcp-server` | Server name reported over MCP and by `GET /`. |
  73. | `SERVER_VERSION` | the package's own version | Version reported over MCP `initialize`, by `GET /`, and by `bookstack_server_info`. Defaults to `package.json#version`; leave it unset unless you deliberately want a different value. |
  74. | `RATE_LIMIT_REQUESTS_PER_MINUTE` | `60` | Outbound rate limit toward BookStack. |
  75. | `RATE_LIMIT_BURST_LIMIT` | `10` | Outbound burst allowance toward BookStack. |
  76. | `VALIDATION_ENABLED` | `true` | Input validation. Set to `false` to disable. |
  77. | `VALIDATION_STRICT_MODE` | `true` | Reject invalid tool params at the boundary. Set to `false` to log a warning and forward them to BookStack instead. |
  78. | `LOG_LEVEL` | `info` | One of `error`, `warn`, `info`, `debug`. |
  79. | `LOG_FORMAT` | `pretty` | One of `json`, `pretty`. |
  80. | `NODE_ENV` | `development` | One of `development`, `production`, `test`. |
  81. | `DEBUG` | `false` | Set to `true` for debug output. |
  82. > 💡 Need detailed setup? See the complete [Setup Guide](docs/setup-guide.md)
  83. ## 🔌 Transports
  84. The transport is chosen at startup from `MCP_TRANSPORT`:
  85. | `MCP_TRANSPORT` | Result |
  86. | --- | --- |
  87. | unset (**default**) | Streamable HTTP server on `SERVER_PORT` (default `3000`) |
  88. | `http` | Same as unset |
  89. | `stdio` | Stdio transport — reads MCP messages from stdin |
  90. **Stdio is opt-in.** If you do not set `MCP_TRANSPORT=stdio`, you get the HTTP server.
  91. ### HTTP endpoints
  92. When running in HTTP mode the server exposes exactly three endpoints. Any other
  93. path returns a JSON `404` listing the valid ones.
  94. | Method & path | Purpose | Status codes |
  95. | --- | --- | --- |
  96. | `GET /` | Server info JSON (name, version, `status: "running"`, endpoint list) | `200` |
  97. | `GET /health` | Health check — verifies live connectivity to BookStack | `200` healthy, `503` unhealthy |
  98. | `POST /message` | **The MCP endpoint.** Send JSON-RPC MCP messages here | `200`, `401` without a valid bearer token, `500` on error |
  99. `GET /` and `GET /health` are unauthenticated. **`POST /message` requires an inbound
  100. `Authorization: Bearer <secret>` header** — it dispatches every tool, including
  101. permanent-delete and user/role operations, so the HTTP transport refuses to start
  102. without a secret configured. The startup error names the exact variable to set; the
  103. `stdio` transport has no network surface and needs none.
  104. **Check the server is up:**
  105. ```bash
  106. curl http://localhost:3000/
  107. ```
  108. ```json
  109. {
  110. "name": "bookstack-mcp-server",
  111. "version": "1.0.0",
  112. "status": "running",
  113. "mcp": true,
  114. "endpoints": {
  115. "health": "/health",
  116. "message": "/message (POST, requires an Authorization: Bearer header)"
  117. },
  118. "documentation": "Send MCP protocol messages to POST /message"
  119. }
  120. ```
  121. **Check health:**
  122. ```bash
  123. curl -i http://localhost:3000/health
  124. ```
  125. `/health` verifies live connectivity to BookStack, so a **wrong** token returns `503`
  126. with the failing check named:
  127. ```json
  128. {
  129. "status": "unhealthy",
  130. "checks": [
  131. { "name": "bookstack_connection", "healthy": false, "message": "BookStack API connection" },
  132. { "name": "tools_loaded", "healthy": true, "message": "59 tools loaded" },
  133. { "name": "resources_loaded", "healthy": true, "message": "11 resources loaded" }
  134. ]
  135. }
  136. ```
  137. > ⚠️ A **missing** `BOOKSTACK_API_TOKEN` behaves differently: config validation rejects
  138. > an empty token at startup, so the process exits with
  139. > `Configuration validation failed: bookstack.apiToken: BookStack API token is required`
  140. > before Express ever listens. There is no `/health` to call — `curl` gets a connection
  141. > refused, and under Docker the container restart-loops. A `503` therefore always means
  142. > the token is **present but not working**; a dead port means it is **absent**.
  143. **Call the MCP endpoint** — an `initialize` handshake. Both the `Content-Type`
  144. and `Accept` headers are required by the Streamable HTTP transport, and
  145. `Authorization` carries the same `MCP_AUTH_TOKEN` you exported in the quick start:
  146. ```bash
  147. # Fail fast rather than sending an empty bearer header and puzzling over a 401.
  148. : "${MCP_AUTH_TOKEN:?export MCP_AUTH_TOKEN first — the inbound secret this server was started with}"
  149. curl -X POST http://localhost:3000/message \
  150. -H "Content-Type: application/json" \
  151. -H "Accept: application/json, text/event-stream" \
  152. -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  153. -d '{
  154. "jsonrpc": "2.0",
  155. "id": 1,
  156. "method": "initialize",
  157. "params": {
  158. "protocolVersion": "2024-11-05",
  159. "capabilities": {},
  160. "clientInfo": { "name": "curl", "version": "1.0.0" }
  161. }
  162. }'
  163. ```
  164. Per-request credential overrides are supported on `POST /message` via the
  165. `x-bookstack-url` and `x-bookstack-token` headers; both fall back to the
  166. `BOOKSTACK_BASE_URL` / `BOOKSTACK_API_TOKEN` environment variables.
  167. ### Using with n8n
  168. Point n8n's MCP client at the `/message` path — not the root URL:
  169. ```
  170. http://<host>:3000/message
  171. ```
  172. Use the host as n8n sees it: `http://localhost:3000/message` when n8n runs on
  173. the same machine, or the container/service name (e.g. `http://mcp:3000/message`)
  174. when both run in Docker on a shared network.
  175. ### Running stdio in Docker
  176. A stdio MCP server reads requests from **stdin** — so `docker run` without `-i`
  177. gives it no stdin, stdin hits EOF immediately, and the container exits on
  178. startup. Pass `-i` to keep stdin attached:
  179. ```bash
  180. docker run -i --rm \
  181. -e MCP_TRANSPORT=stdio \
  182. -e BOOKSTACK_BASE_URL=https://your-bookstack.com/api \
  183. -e BOOKSTACK_API_TOKEN=token_id:token_secret \
  184. bookstack-mcp-server
  185. ```
  186. Use `-i` alone, **not** `-it`: allocating a TTY breaks the JSON-RPC stream that
  187. MCP clients pipe over stdin/stdout. For stdio you also don't need `-p 3000:3000`
  188. — nothing listens on a port in stdio mode.
  189. > If your container "starts then dies immediately" with `MCP_TRANSPORT=stdio`,
  190. > a missing `-i` is almost always the cause.
  191. ## 🛠️ Available Tools
  192. **59 tools across 13 categories:**
  193. - **📚 Books** (6) - Create, read, update, delete, and export books
  194. - **📄 Pages** (9) - Manage pages with HTML/Markdown content, including [partial editing](#-partial-page-editing)
  195. - **📑 Chapters** (6) - Organize pages within books
  196. - **📚 Shelves** (5) - Group books into collections
  197. - **🔍 Search** (1) - Search across content types
  198. - **👥 Users** (5) - User account management
  199. - **🎭 Roles** (5) - Roles and their permissions
  200. - **⚙️ System** (2) - Instance info and the audit log
  201. - **🔐 Permissions** (2) - Content access control
  202. - **🗑️ Recycle Bin** (3) - Deleted item recovery
  203. - **📎 Attachments** (5) - File attachments
  204. - **🖼️ Images** (5) - Image gallery
  205. - **🧭 Meta** (5) - Ask the server about its own tools and conventions
  206. Not exposed (no tools): comments, imports, tag-name listings, the image-gallery
  207. `data` endpoints, and `zip` export.
  208. > 📖 See the complete [Tools Overview](docs/tools-overview.md) for detailed documentation
  209. ## ✂️ Partial page editing
  210. The BookStack API has no PATCH for page content — `PUT /api/pages/{id}` takes a complete
  211. `html` or `markdown` body. Changing one paragraph of a long page therefore meant reading all
  212. of it, having the model reproduce it verbatim with the change applied, and sending it all
  213. back: the content crosses the model twice, and the whole page rides on it being copied
  214. byte-perfectly.
  215. Three tools run that read-modify-write cycle inside the server instead, so a caller sends
  216. only the fragment it wants changed:
  217. | Tool | What it does |
  218. |---|---|
  219. | `bookstack_pages_outline` | Heading structure with offsets and section sizes. No content transferred. |
  220. | `bookstack_pages_read` with `grep` | Matching excerpts from the **stored** source — paste one straight into `old_string`. |
  221. | `bookstack_pages_edit` | Literal find-and-replace. `old_string` must match exactly and be unique unless `replace_all` is set. |
  222. | `bookstack_pages_append` | Insert at the end of the page, the end of a named section, or right after a section heading. |
  223. ```jsonc
  224. // 1. What sections exist, and how big are they?
  225. { "tool": "bookstack_pages_outline", "arguments": { "id": 12 } }
  226. // 2. Get an exact anchor without loading the page
  227. { "tool": "bookstack_pages_read",
  228. "arguments": { "id": 12, "grep": "retention period", "context": 300 } }
  229. // 3. Rehearse: nothing is written
  230. { "tool": "bookstack_pages_edit",
  231. "arguments": { "id": 12, "dry_run": true,
  232. "edits": [{ "old_string": "retention period of 6 months",
  233. "new_string": "retention period of 24 months" }] } }
  234. // 4. Apply with a stale-page preflight
  235. { "tool": "bookstack_pages_edit",
  236. "arguments": { "id": 12, "expected_updated_at": "2026-08-17T09:12:44.000000Z",
  237. "edits": [{ "old_string": "retention period of 6 months",
  238. "new_string": "retention period of 24 months" }] } }
  239. ```
  240. **Guards.** An ambiguous anchor is refused rather than applied to the wrong place, and the
  241. error carries the first few matches with context. A missing anchor reports the same text found
  242. with different whitespace, which is the usual near-miss. A result smaller than half the
  243. original is refused unless `allow_shrink` is set. After a write the page is re-read and the
  244. change is looked for in normalised text — BookStack rewrites stored HTML on save (heading
  245. anchors, injected `id` attributes), so a byte comparison would call every success a failure.
  246. Every write creates a BookStack revision, so an applied edit can be rolled back in the UI.
  247. No response from these tools contains page content.
  248. `expected_updated_at` detects a page changed before this server reads it; BookStack's page
  249. API does not provide an atomic version condition, so it cannot prevent a write that races
  250. after that check.
  251. **Two invariants**, if you touch this code (`src/utils/page-content.ts`): markdown pages are
  252. patched and written through `markdown`, because writing `html` to one switches the page's
  253. editor type; every other page is patched against `raw_html`, never the rendered `html` —
  254. patching the rendered output would write back expanded page-include tags and destroy the
  255. includes permanently.
  256. `bookstack_pages_update` is unchanged and still replaces the whole content field; these tools
  257. are additive. `bookstack_pages_read` called without any of the new options returns exactly
  258. what it always did.
  259. ## 📚 Documentation
  260. Find comprehensive guides in the `docs/` folder:
  261. - **[Setup Guide](docs/setup-guide.md)** - Complete installation and configuration
  262. - **[API Reference](docs/api-reference.md)** - Supported tools/endpoints with examples
  263. - **[Tools Overview](docs/tools-overview.md)** - Every tool explained
  264. - **[Resources Guide](docs/resources-guide.md)** - Resource access patterns
  265. - **[Examples & Workflows](docs/examples-and-workflows.md)** - Real-world usage
  266. - **[Integration Testing](docs/integration-testing.md)** - Running the live suite against a real BookStack
  267. - **[Releasing](docs/releasing.md)** - How versions are cut and published
  268. ## ⚡ Quick Examples
  269. **List all books:**
  270. ```javascript
  271. bookstack_books_list({ count: 10, sort: "updated_at" })
  272. ```
  273. **Create a new page:**
  274. ```javascript
  275. bookstack_pages_create({
  276. name: "Getting Started",
  277. book_id: 1,
  278. markdown: "# Welcome\nYour content here..."
  279. })
  280. ```
  281. **Search for content:**
  282. ```javascript
  283. bookstack_search({ query: "API documentation", count: 20 })
  284. ```
  285. ## 🛠️ Development
  286. This project is Bun-native — Bun runs the TypeScript source directly, so there is
  287. no compile step.
  288. ```bash
  289. git clone <repository-url>
  290. cd bookstack-mcp-server
  291. bun install
  292. bun run dev # hot reload; equivalent to: bun --watch src/server.ts
  293. ```
  294. ```bash
  295. bun run src/server.ts # start the server
  296. bun test # run tests
  297. bun run typecheck # tsc --noEmit
  298. bun run lint # biome check .
  299. ```
  300. > 🔧 See the [Setup Guide](docs/setup-guide.md) for development, Docker, and production deployment
  301. ## 🐳 Local testing with Docker Compose
  302. The included `docker-compose.yml` spins up a full local stack — MariaDB, a real
  303. BookStack instance, and this MCP server (built from the Bun `Dockerfile`).
  304. 1. **Start the backing services:**
  305. ```bash
  306. docker compose up -d db bookstack
  307. ```
  308. 2. **Wait for BookStack** to finish first-boot migrations, then open
  309. <http://localhost:6875>. Default linuxserver credentials:
  310. - Email: `admin@admin.com`
  311. - Password: `password`
  312. 3. **Create an API token** in the UI (Edit Profile → **API Tokens** → *Create
  313. Token*). Combine the Token ID and Token Secret as `token_id:token_secret` and
  314. put it in a `.env` file next to `docker-compose.yml`, together with an inbound
  315. secret of your own:
  316. ```bash
  317. echo "BOOKSTACK_API_TOKEN=token_id:token_secret" > .env
  318. echo "MCP_AUTH_TOKEN=$(openssl rand -hex 32)" >> .env
  319. ```
  320. > The token can only be created after BookStack is running, so it cannot be
  321. > baked into the image — this manual step is required once.
  322. >
  323. > **Both** entries are required. `docker-compose.yml` passes `MCP_AUTH_TOKEN`
  324. > through to the `mcp` service, and the HTTP transport refuses to start without
  325. > it, so a `.env` carrying only `BOOKSTACK_API_TOKEN` leaves the container in a
  326. > restart loop.
  327. 4. **Start the MCP server** (it reads both tokens from `.env`):
  328. ```bash
  329. docker compose up -d mcp
  330. ```
  331. 5. **Check health** — returns `200` with `{"status":"healthy"}` once the server
  332. can reach BookStack with your token:
  333. ```bash
  334. curl http://localhost:3000/health
  335. ```
  336. Until a **valid** `BOOKSTACK_API_TOKEN` is supplied the `mcp` container reports
  337. `unhealthy`, because `/health` verifies live connectivity to BookStack. If either token is
  338. **missing entirely** the container does not get that far and restart-loops instead of
  339. answering `503` — check `docker compose logs mcp` for `Configuration validation failed`
  340. (no `BOOKSTACK_API_TOKEN`) or `MCP_AUTH_TOKEN is not set` (no inbound secret).
  341. The compose file pins BookStack to `lscr.io/linuxserver/bookstack:version-v26.05.2` — the
  342. release this repo's tool contract was verified against — and ships a throwaway dev
  343. `APP_KEY`. Generate your own for anything beyond local testing, using the same pinned tag:
  344. ```bash
  345. docker run --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:version-v26.05.2 appkey
  346. ```
  347. It prints one `base64:…` line to paste into `APP_KEY`. The `--entrypoint` override is
  348. required: without it the image runs its normal init first, which halts with
  349. `The application key is missing, halting init!` — the very key you are trying to
  350. generate — and never reaches the `appkey` script.
  351. ## 📝 License
  352. MIT License - see [LICENSE](LICENSE) file for details.
  353. ## 🌟 Community
  354. This project is part of the BookStack ecosystem! Check out other API-based tools and scripts in the [BookStack API Scripts](https://codeberg.org/bookstack/api-scripts) repository.
  355. ## 🆘 Support
  356. - **📚 Documentation**: Complete guides in the [docs/](docs/) folder
  357. - **🐛 Issues**: [GitHub Issues](https://github.com/pnocera/bookstack-mcp-server/issues)
  358. - **💬 Discussions**: [GitHub Discussions](https://github.com/pnocera/bookstack-mcp-server/discussions)
  359. ---
  360. **Built with ❤️ for the BookStack community**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.