Which integrations are available for this server?

Provides comprehensive management of BookStack instances, including unified CRUD operations for books, bookshelves, chapters, and pages, full-text search, and advanced image gallery management with support for URL-based uploads.

How do I use BookStack MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BookStack MCP Server search for all pages related to the server migration guide" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

BookStack MCP Server

This repository hosts a Python FastMCP-based server that exposes consolidated tools for managing a BookStack instance. The flagship capabilities are the image gallery management workflows that power authoring experiences in downstream MCP clients.

⚠️ DEPRECATION NOTICE: The TypeScript/mcp-framework server (src/ directory) is deprecated and no longer maintained. All development has moved to the Python FastMCP server (fastmcp_server/ directory). Please migrate to the Python server for the latest features and bug fixes.

Quick start

# Install Python dependencies for the FastMCP server pip install -r fastmcp_server/requirements.txt

Launch the FastMCP server after exporting your BookStack credentials (see below):

cd fastmcp_server python3 -m fastmcp_server

Required environment

Copy .env.example to .env and populate these variables before invoking any BookStack tools:

BS_URL=https://your-bookstack.example.com BS_TOKEN_ID=... BS_TOKEN_SECRET=...

The API token must belong to a user that can view and manage the image gallery. Local helper scripts use set -a && source .env so the values apply to ad-hoc Python snippets as well.

BookStack tools

The Python FastMCP server provides comprehensive BookStack management through consolidated tools:

Content Management

bookstack_content_crud — unified CRUD operations for books, bookshelves, chapters, and pages (Letta-compatible)
bookstack_list_content — list and filter content entities with pagination
bookstack_search — full-text search across BookStack content
bookstack_batch_operations — bulk create, update, and delete operations

Image Gallery Management

bookstack_manage_images — unified create/read/update/delete/list interface for images
bookstack_search_images — advanced discovery with extension, date, size, and usage filters

All tools are registered by fastmcp_server/bookstack/tools.py and surfaced automatically when the FastMCP server starts.

📘 Letta Compatibility: If you're using Letta as your MCP client, please read docs/LETTA_COMPATIBILITY.md for important compatibility requirements and best practices.

Image uploads from URLs

bookstack_manage_images accepts three input shapes for the image/new_image fields during create and update operations:

Plain base64 strings
Data URLs (data:image/png;base64,...)
HTTP or HTTPS URLs

When a URL is supplied the tool:

Streams the remote image with a 30 second timeout and a 50 MB limit
Restricts schemes to HTTP/HTTPS to avoid SSRF
Validates the MIME type against BookStack's accepted formats (jpeg, png, gif, webp, bmp, tiff, svg+xml)
Infers a filename from the URL path when one is not supplied

Required BookStack parameters

BookStack's POST /api/image-gallery endpoint enforces two additional fields beyond the binary payload:

type — must be gallery for standard content images (use drawio only when uploading diagrams.net PNGs)
uploaded_to — the numeric page ID to attach the image to. BookStack rejects uploads without a real page context.

The tool surfaces these as optional inputs named image_type and uploaded_to. Default values of gallery and 0 preserve backward compatibility while allowing callers to target specific pages when required.

Manual verification against a live instance

After exporting your environment variables you can confirm an end-to-end URL upload with the following snippet (replace PAGE_ID with an existing page id):

cd /opt/stacks/bookstack-mcp/Bookstack-MCP set -a && source .env && set +a python3 - <<'PY' import asyncio, json, time from fastmcp import FastMCP from fastmcp_server.bookstack.tools import register_bookstack_tools TEST_IMAGE_URL = "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" PAGE_ID = 39 # replace with a page id from your BookStack instance async def main(): mcp = FastMCP("manual-test") register_bookstack_tools(mcp) tool = await mcp.get_tool("bookstack_manage_images") result = await tool.run({ "operation": "create", "name": f"URL Upload Test {int(time.time())}", "image": TEST_IMAGE_URL, "uploaded_to": PAGE_ID, }) print(json.dumps(json.loads(result.content[0].text), indent=2)) asyncio.run(main()) PY

You should receive a JSON payload describing the uploaded image, including thumbnails and the uploaded_to identifier. A 422 error means BookStack rejected the request (common causes: missing uploaded_to, disallowed MIME type, image exceeding the 50 MB limit). A 404 response typically indicates the API token lacks gallery permissions.

Testing

Run the Python unit tests for the BookStack tools:

cd fastmcp_server python3 -m pytest tests/test_manage_images.py -v

The suite covers URL handling, timeout and size enforcement, invalid scheme rejection, and the forwarding of type/uploaded_to metadata.

Additional references

FastMCP docs: https://gofastmcp.com/
BookStack API reference: https://www.bookstackapp.com/docs/api/
Product requirements for the image gallery tools: docs/PRD-Image-Gallery-Management.md