BookStack MCP

Prerequisites

• A BookStack instance with API access enabled
• A BookStack API token (created in your BookStack user profile under "API Tokens")
• Docker and Docker Compose (for container deployment)

Setup

Semantic Search Setup

1. Set BSMCP_SEMANTIC_SEARCH=true in your server env
2. Set BSMCP_WEBHOOK_SECRET to a random string (16+ characters)
3. Create a BookStack API token with read access for the embedder (BSMCP_EMBED_TOKEN_ID / BSMCP_EMBED_TOKEN_SECRET)
4. Start the embedder container — it downloads the ONNX model (~1.3GB) on first run
5. Use the reembed tool (via Claude) to trigger initial embedding of all pages
6. Configure a webhook in BookStack for automatic re-embedding on page changes:

BookStack Webhook Configuration

Go to Settings > Webhooks > Create Webhook in your BookStack instance:

Events to select: - Page Create - Page Update - Page Delete

Custom header (required for verification):

X-Webhook-Secret: YOUR_WEBHOOK_SECRET

The YOUR_WEBHOOK_SECRET value must match BSMCP_WEBHOOK_SECRET in your server environment. The server uses constant-time comparison to verify the header.

After saving, any page create/update/delete in BookStack automatically queues a re-embedding job. The embedder picks it up within seconds (configurable via BSMCP_EMBED_POLL_INTERVAL).

Reranker Setup (optional — for the `rerank: true` flag and `mode: "precision"`)

The cross-encoder reranker is off by default. semantic_search (default mode: "standard", rerank: false) and search_content (default rerank: false) both work fine without it. To enable the rerank: true flag on either tool, or to use mode: "precision" on semantic_search:

1. Pick a provider and set BSMCP_RERANK_PROVIDER on the embedder to one of: - local — in-process ONNX cross-encoder via fastembed. No API key. Default model: BAAI/bge-reranker-v2-m3 (~600 MB, downloads on first run). Reuses BSMCP_MODEL_PATH for the cache directory. - voyage — Voyage AI's /v1/rerank. Set BSMCP_RERANK_API_KEY. Default model: rerank-2. - openai — any OpenAI-shape /v1/rerank endpoint (Voyage, Jina, Cohere-via-shim, self-hosted). Requires all of BSMCP_RERANK_API_KEY, BSMCP_RERANK_API_URL, and BSMCP_RERANK_MODEL (no upstream default — OpenAI itself has not shipped a rerank API). 2. Restart the embedder. On startup it logs Reranker: <provider> <model> and starts answering POST /rerank. Without configuration it logs Reranker: disabled (BSMCP_RERANK_PROVIDER unset or 'none') and /rerank returns 503. 3. Use the reranker from a tool call: - semantic_search with mode: "standard", rerank: true — runs the standard pipeline, then the cross-encoder re-orders the top-N. Equivalent to the pre-v0.13.0 mode: "rerank". - semantic_search with mode: "precision" — wider candidate pool, cross-encoder is the ranker of record (4-stage cascade; rerank is always on). - search_content with rerank: true — BookStack keyword search, then the cross-encoder re-orders the matched results. In all three cases the response includes scoring.rerank per result and stats.{rerank_ms, rerank_provider, rerank_model, candidates_reranked}. If the reranker is disabled, the server surfaces a clear error pointing at BSMCP_RERANK_PROVIDER so callers can drop the flag and retry.

Per-provider config blocks are documented under Reranker Providers.

Quick Start (PostgreSQL — recommended)

```bash cp .env.example .env

Quick Start (SQLite — simple)

```bash cp .env.example .env

Edit .env with your BookStack URL, encryption key, and database password

docker compose -f docker/docker-compose.yml up -d ```

This starts four containers: - bsmcp-postgres — PostgreSQL 17 with pgvector extension - bsmcp-server — MCP server (port 8080) - bsmcp-embedder — Background embedding service (--role=embedder, default); also serves /rerank when a reranker is configured - bsmcp-worker — Reconciliation worker (same image as the embedder, started with --role=worker): initial walk on cold start, webhook + cron job consumption, periodic delta walk

Edit .env with your BookStack URL and encryption key

docker compose -f docker/docker-compose.sqlite.yml up -d ```

This starts three containers (server + embedder + worker) sharing a SQLite database file.

Configuration

Server Variables

Embedder Variables

Role Selector

The embedder image hosts both the embedder loop and the reconciliation worker loop. Select which runs per container via --role (CLI flag, primary) or BSMCP_ROLE (env fallback). Default is embedder.

The CLI flag wins over the env. Setting both (compose command: + BSMCP_ROLE) is belt-and-suspenders — recommended for clarity in compose files.

Worker Variables

Read when the embedder is running with --role=worker or --role=both. The worker shares the same database as the server and owns the index_jobs queue.

\* Required, but the fallback to BSMCP_EMBED_TOKEN_* covers most setups.

Job Lifecycle Variables

Read by the worker role's lifecycle housekeeper. Apply to both embed_jobs and index_jobs.

See .env.example for the full list with comments.

API Endpoints

Uses BSMCP_EMBED_TOKEN_ID/SECRET for BookStack API access

**Optional: Switch to Ollama/OpenAI embeddings** — set `BSMCP_EMBED_PROVIDER`:

Alternative: `url` parameter

If the file is already hosted at a public URL the MCP server can reach, you can skip the staging flow entirely and pass the url parameter directly to upload_image or upload_attachment. The server will fetch the file and forward it to BookStack.