Bookstack MCP
About
An MCP server for interacting with Bookstack, built with the mcp-framework for Node.js.
Details
- Author
- oculairmedia
- Categories
- Productivity, Other, Knowledge Base
Jump to
Setup
Install Bookstack MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/oculairmedia/Bookstack-MCP
Follow the installation instructions in the repository README, then restart your MCP client.
This repository hosts aPython FastMCP-based serverthat 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.
# 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
Copy.env.exampleto.envand 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 useset -a && source .envso the values apply to ad-hoc Python snippets as well.
The Python FastMCP server provides comprehensive BookStack management through consolidated tools:
- 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
- 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 byfastmcp_server/bookstack/tools.pyand surfaced automatically when the FastMCP server starts.
📘 Letta Compatibility: If you're using Letta as your MCP client, please readdocs/LETTA_COMPATIBILITY.mdfor important compatibility requirements and best practices.
bookstack_manage_imagesaccepts three input shapes for theimage/new_imagefields during create and update operations:
- Plain base64 strings
- Data URLs (data:image/png;base64,...)
- HTTP or HTTPS URLs
- Streams the remote image with a 30 second timeout and a 50 MB limit
- Restricts schemes to HTTP/HTTPS and blocks loopback, private, link-local, reserved, and redirect-based internal targets
- 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
BookStack'sPOST /api/image-galleryendpoint enforces two additional fields beyond the binary payload:
- type— must begalleryfor standard content images (usedrawioonly 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 namedimage_typeanduploaded_to. Default values ofgalleryand0preserve 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 (replacePAGE_IDwith 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 theuploaded_toidentifier. A422error means BookStack rejected the request (common causes: missinguploaded_to, disallowed MIME type, image exceeding the 50 MB limit). A404response typically indicates the API token lacks gallery permissions.
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 oftype/uploaded_tometadata.
- 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
MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.
Integrates Model Context Protocol (MCP) with Obsidian, allowing AI assistants to interact with your notes and vault.
CLI & MCP server for Zotero 7/8 — 52 tools to let AI manage your research library locally. Search, import, export, PDF, notes, and more.
A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.
Semantic search and RAG over Apple Notes with on-device embeddings, full CRUD, folder management, and fuzzy title matching. 10 tools. Fully local on macOS.
A service for reading, writing, and managing markdown documentation with frontmatter metadata.
Connect your AI assistant to your personal knowledge base. Search, save links, create notes and to-dos. AI processes everything automatically.
An MCP server for interacting with Obsidian notes. Requires the OBSIDIAN_VAULT_PATH environment variable to be set.
Interact with your Obsidian vault using natural language.
Interact with your Obsidian vault using the Local REST API plugin, enabling LLMs to access and manage your notes.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
