bookstack-mcp

This is an HTTP MCP server that allows your agents to communicated with Bookstack.

I built this MCP server because I use bookstack pretty heavily. I could not find a good solution for letting my LLM read and update books using an HTTP powered MCP server.

Getting started

I built this with the intention that it would run alongside bookstack using docker compose.

Configuration

The server is configured with environment variables (a local .env file is also loaded — see .env.example):

Variable	Required	Default	Description
BOOKSTACK_BASE_URL	yes	—	Root URL of the BookStack instance to talk to (e.g. http://bookstack:6875).
PORT	no	3000	Port the MCP HTTP server listens on.
LOG_LEVEL	no	info	Winston log level: error, warn, info, or debug.

Note the BookStack API token is not configured on the server. Each request carries the token and the server forwards it to BookStack, so a single instance can serve multiple users/tokens — see Authentication below.

Example docker compose

The server is meant to run on the same Docker network as BookStack so it can reach it by service name. Point BOOKSTACK_BASE_URL at the bookstack service (over the internal network) rather than a public/localhost URL:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      APP_URL: http://localhost:6875
      # BookStack also needs a database service and its DB_* settings.
      # See https://www.bookstackapp.com/docs/admin/installation/ for a
      # complete BookStack + MySQL compose setup.
    ports:
      - "6875:6875"

  bookstack-mcp:
    build: .
    environment:
      BOOKSTACK_BASE_URL: http://bookstack:6875
      PORT: "6045"
      LOG_LEVEL: info
    ports:
      - "6045:6045"
    depends_on:
      - bookstack

Then point your MCP client at http://<host>:6045/mcp. A GET /health endpoint is available for container health checks.

Authentication

Create an API token in BookStack (Edit Profile → API Tokens → Create Token), which gives you a Token ID and a Token Secret. Send them on every request in the Authorization header, joined with a colon:

Authorization: Token <token_id>:<token_secret>

The Token / Bearer scheme prefix is optional (a raw <id>:<secret> value is also accepted). Requests without a token are rejected with 401. The server forwards the token to BookStack, so it inherits exactly the permissions of that token's user.

Available tools

The server exposes two tools over the MCP endpoint (POST /mcp).

bookstack_search

Search across all BookStack content (shelves, books, chapters, and pages).

This tool is Read-only.

Argument	Required	Description
query	yes	Search text, using BookStack search syntax (e.g. cats {created_by:me}).
page	no	1-based page number.
count	no	Results per page (max 100).

bookstack_crud

Create, read, update, delete, or list BookStack entities. Works across four entity types: book, chapter, page, and shelf.

Argument	Required	Description
entity	yes	book, chapter, page, or shelf.
operation	yes	create, read, update, delete, or list.
id	for read/update/delete	Numeric ID of the target entity.
data	for create/update	Entity fields (see below). Validated per entity before sending.
params	optional, for list	{ count (max 500), offset, sort, filter } — e.g. sort: "-created_at", filter: { book_id: 3 }.

data fields by entity (* = required on create; all optional on update):

Entity	Fields
book	name*, description, description_html, tags [{name,value}], default_template_id
chapter	book_id*, name*, description, description_html, tags, priority, default_template_id
page	name*, book_id or chapter_id*, html or markdown*, tags, priority
shelf	name*, description, description_html, books [bookId, ...], tags

Both tools return the BookStack API response as JSON. Errors (validation failures or BookStack API errors) come back as tool errors with a descriptive message.