{
"markdown": "# BookStack MCP Server\n\n[](https://www.npmjs.com/package/bookstack-mcp)\n[](https://www.npmjs.com/package/bookstack-mcp)\n[](https://github.com/ttpears/bookstack-mcp/actions/workflows/ci.yml)\n[](https://nodejs.org)\n[](https://modelcontextprotocol.io)\n[](https://opensource.org/licenses/MIT)\n\n![\"bookstack-mcp\"/](\"assets/logo.svg\")
\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI assistants full access to your [BookStack](https://www.bookstackapp.com) documentation — search, read, create, and manage content.\n\n```bash\nnpx bookstack-mcp\n```\n\n## Features\n\n- 20 read-only tools + 20 write tools for complete BookStack API coverage\n- Books, chapters, pages, shelves, attachments, and comments — full CRUD\n- Recycle bin support — restore or permanently delete soft-deleted content\n- Type-safe input validation with Zod (auto-coerces string/number params for broad client compatibility)\n- Embedded URLs and content previews in all responses\n- Markdown export fallback for HTML-authored pages, so AI clients always get usable content\n- Token-efficient responses: compact JSON, no redundant fields, no N+1 fetches — ~30–55% smaller payloads than 3.x\n- Write operations disabled by default for safety\n- Works with Claude Desktop, Claude Code, LibreChat, and any MCP-compatible client\n- Stdio and Streamable HTTP transports\n\n## Quick Start\n\n### Install from npm\n\n```bash\nnpx bookstack-mcp\n```\n\n### Or clone and build\n\n```bash\ngit clone https://github.com/ttpears/bookstack-mcp.git\ncd bookstack-mcp\nnpm install && npm run build\nnpm start\n```\n\n### Environment Variables\n\n```env\nBOOKSTACK_BASE_URL=https://your-bookstack.com # Required\nBOOKSTACK_TOKEN_ID=your-token-id # Required\nBOOKSTACK_TOKEN_SECRET=your-token-secret # Required\nBOOKSTACK_ENABLE_WRITE=false # Optional, default false\nBOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false # Optional, default false\n```\n\n> **Security warning:** `BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=true` disables TLS certificate verification for outgoing requests to BookStack. Use only for self-signed certs on a trusted LAN — connections become vulnerable to MITM attacks. The server logs a `WARNING` line at startup whenever this is enabled.\n\n## Client Configuration\n\n### Claude Desktop\n\nThe easiest install is the prebuilt MCPB bundle attached to each [GitHub release](https://github.com/ttpears/bookstack-mcp/releases/latest):\n\n1. Download `bookstack-mcp-.mcpb` from the latest release.\n2. Open Claude Desktop → **Settings → Extensions** and drag the `.mcpb` file in (or click *Install Extension*).\n3. Fill in **BookStack URL**, **API Token ID**, and **API Token Secret**. Tokens are stored in your OS keychain. Leave **Enable Write Operations** as `false` for read-only access; set to `true` to enable create/update/delete tools.\n\n#### Manual install (JSON config)\n\nIf you'd rather edit the config file directly:\n\n```json\n{\n \"mcpServers\": {\n \"bookstack\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bookstack-mcp\"],\n \"env\": {\n \"BOOKSTACK_BASE_URL\": \"https://your-bookstack.com\",\n \"BOOKSTACK_TOKEN_ID\": \"your-token-id\",\n \"BOOKSTACK_TOKEN_SECRET\": \"your-token-secret\"\n }\n }\n }\n}\n```\n\n### LibreChat (stdio, single-user)\n\nAdd to your `librechat.yaml`:\n\n```yaml\nmcpServers:\n bookstack:\n command: npx\n args:\n - -y\n - bookstack-mcp\n env:\n BOOKSTACK_BASE_URL: \"https://your-bookstack.com\"\n BOOKSTACK_TOKEN_ID: \"your-token-id\"\n BOOKSTACK_TOKEN_SECRET: \"your-token-secret\"\n```\n\n### LibreChat (Streamable HTTP, recommended for production / Docker)\n\nRun the server as a long-lived HTTP service and point LibreChat at the URL. This is the right setup for multi-user or containerized deployments.\n\nStart the server in HTTP mode:\n\n```bash\nMCP_TRANSPORT=http \\\nMCP_HTTP_PORT=8080 \\\nBOOKSTACK_BASE_URL=https://your-bookstack.com \\\nBOOKSTACK_TOKEN_ID=your-token-id \\\nBOOKSTACK_TOKEN_SECRET=your-token-secret \\\nnpx bookstack-mcp\n```\n\nThen configure LibreChat:\n\n```yaml\nmcpServers:\n bookstack:\n type: streamable-http\n url: http://bookstack-mcp:8080/mcp\n```\n\n> **3.0.0 breaking change:** the deprecated HTTP+SSE transport (`GET /sse` + `POST /messages`) has been removed. Streamable HTTP at `/mcp` already speaks SSE for streaming responses, and is the only HTTP transport in current MCP clients. If you're on an older client that needs the legacy endpoints, pin to `bookstack-mcp@2.x`.\n\n#### HTTP transport environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_TRANSPORT` | `stdio` | Set to `http` to enable the HTTP server |\n| `MCP_HTTP_PORT` | `8080` | Port to listen on |\n| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address. Loopback by default for safety |\n| `MCP_HTTP_ALLOWED_HOSTS` | *(loopback only)* | Comma-separated allowlist of `Host` header hostnames for DNS rebinding protection. Required when binding to a non-loopback address |\n| `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP endpoint |\n\nWhen binding to `0.0.0.0` (e.g. inside a container reachable from other services), set `MCP_HTTP_ALLOWED_HOSTS` to the hostnames LibreChat will use to reach this server, e.g. `MCP_HTTP_ALLOWED_HOSTS=bookstack-mcp,bookstack-mcp.internal`.\n\nRestart LibreChat after config changes.\n\n### Remote hosting & Claude Connector (Docker + Entra OAuth)\n\nA container image is published to `ghcr.io/ttpears/bookstack-mcp` (released `:X.Y.Z`/`:latest`,\nplus per-PR preview tags `:branch-`). The server can run as a public **Claude Connector**\ngated by Microsoft 365 / Entra ID login — users sign in, no API key or client credential to\npaste; write tools are unlocked per session by an Entra app role.\n\nSee **[docs/SETUP.md](docs/SETUP.md)** for the full runbook: Entra app registration steps,\nthe environment-variable reference, internal LibreChat deployment, and the public OAuth\nconnector setup.\n\n### Claude Code (CLI)\n\nThe recommended path is the `ttpears/claude-plugins` marketplace, which ships this repo's plugin manifest (`.claude-plugin/plugin.json`):\n\n```\n/plugin marketplace add ttpears/claude-plugins\n/plugin install bookstack-mcp@ttpears-plugins\n```\n\nThen set the `BOOKSTACK_*` environment variables in your shell so the plugin's MCP server can authenticate:\n\n```bash\nexport BOOKSTACK_BASE_URL=https://your-bookstack.com\nexport BOOKSTACK_TOKEN_ID=your-token-id\nexport BOOKSTACK_TOKEN_SECRET=your-token-secret\n```\n\n#### Manual install (alternative)\n\nIf you'd rather not use the marketplace, register the server directly with `claude mcp add`. Repeat `--env` for each variable, put all flags **before** the server name, and use `--` to mark the start of the command Claude Code will spawn:\n\n```bash\nclaude mcp add bookstack \\\n --transport stdio \\\n --scope user \\\n --env BOOKSTACK_BASE_URL=https://your-bookstack.com \\\n --env BOOKSTACK_TOKEN_ID=your-token-id \\\n --env BOOKSTACK_TOKEN_SECRET=your-token-secret \\\n -- npx -y bookstack-mcp\n```\n\nScope picks where the entry is written:\n\n| Scope | Where it lives | Shared via git | Use it when |\n|-------|----------------|----------------|-------------|\n| `local` (default) | `~/.claude.json`, scoped to the current project | No | Trying it out in one repo |\n| `user` | `~/.claude.json`, available in every project | No | You want bookstack everywhere |\n| `project` | `.mcp.json` at the repo root | Yes | The whole team should get it |\n\nThe resulting config entry looks like this (in `.mcp.json` for project scope, or `~/.claude.json` otherwise):\n\n```json\n{\n \"mcpServers\": {\n \"bookstack\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bookstack-mcp\"],\n \"env\": {\n \"BOOKSTACK_BASE_URL\": \"https://your-bookstack.com\",\n \"BOOKSTACK_TOKEN_ID\": \"your-token-id\",\n \"BOOKSTACK_TOKEN_SECRET\": \"your-token-secret\"\n }\n }\n }\n}\n```\n\n> **Tip for committed `.mcp.json`:** Claude Code expands `${VAR}` and `${VAR:-default}` references in `.mcp.json` from the surrounding shell. Use that to keep secrets out of git: set `\"BOOKSTACK_TOKEN_SECRET\": \"${BOOKSTACK_TOKEN_SECRET}\"` in the file and have each developer export the variable in their shell.\n\n## MCP Resources\n\nBooks and pages are also exposed as MCP resources, so clients that browse resources (Claude Desktop, MCP Inspector, etc.) can `@`-mention them directly:\n\n| URI template | Description |\n|--------------|-------------|\n| `bookstack://book/{id}` | A book, returned as JSON metadata |\n| `bookstack://page/{id}` | A page, returned as markdown plus a JSON metadata blob |\n\nBoth templates support `id` autocompletion: as you type, the server searches BookStack and returns matching IDs so you don't have to remember numeric IDs by hand.\n\n> **4.0.0 breaking changes:** tool responses were trimmed for token efficiency. Removed fields: `direct_link`, `*_friendly` date strings, `content_info`, `contextual_info`, `change_summary`, `pagination_hint`, `location`, `summary`/`tags_summary`/`book_count` on shelves, and the buggy `page_url` on attachments. Use `url`, the ISO date fields, and `download_url` instead. The `get_capabilities` tool was removed — clients should use `tools/list` (built into MCP). Responses are now compact JSON (no pretty-printing) and `get_recent_changes` no longer issues per-result fetches.\n\n## Available Tools\n\n### Read Operations (always available)\n\n| Tool | Description |\n|------|-------------|\n| `search_content` | Search across all content with filtering |\n| `search_pages` | Search pages with optional book filtering |\n| `get_books` / `get_book` | List or get details of books |\n| `get_pages` / `get_page` | List or get full page content |\n| `get_chapters` / `get_chapter` | List or get chapter details |\n| `get_shelves` / `get_shelf` | List or get shelf details |\n| `get_attachments` / `get_attachment` | List or get attachment details |\n| `get_comments` / `get_comment` | List or get page comments (BookStack v25.11+) |\n| `find_users` | Look up BookStack users by name, email, or slug to resolve user slugs for `{created_by:X}`-style search filters |\n| `get_recycle_bin` | List items in the recycle bin |\n| `export_page` | Export page as HTML, PDF, Markdown, plaintext, or ZIP |\n| `export_book` | Export entire book |\n| `export_chapter` | Export chapter |\n| `get_recent_changes` | Recently updated content |\n\n### Write Operations (requires `BOOKSTACK_ENABLE_WRITE=true`)\n\n| Tool | Description |\n|------|-------------|\n| `create_book` / `update_book` / `delete_book` | Create, update, or delete a book |\n| `create_chapter` / `update_chapter` / `delete_chapter` | Create, update (including moving to a different book or reordering), or delete a chapter |\n| `create_page` | Create a new page (HTML or Markdown) |\n| `update_page` | Update content, rename, or move to a different book/chapter |\n| `delete_page` | Delete a page (recoverable from recycle bin) |\n| `create_shelf` / `update_shelf` / `delete_shelf` | Manage shelves |\n| `create_attachment` / `update_attachment` / `delete_attachment` | Manage attachments |\n| `create_comment` / `update_comment` / `delete_comment` | Manage page comments (v25.11+) |\n| `restore_deleted` / `permanently_delete` | Restore or permanently destroy items in the recycle bin |\n\n## BookStack API Setup\n\n1. Log into BookStack as an admin\n2. Go to **Settings > Users > Edit your user**\n3. Ensure the user has **Access System API** permission\n4. In the **API Tokens** section, create a new token\n5. Copy the Token ID and Token Secret\n\n> **Also grant the role “Export Content”** if you read pages written in the\n> WYSIWYG editor. BookStack returns an empty `markdown` body for those pages, and\n> `get_page` recovers it from the server-side HTML→markdown export endpoint. Without\n> the permission that fallback fails and the page reads as empty. The default Viewer\n> role does not include it.\n\n## Security\n\n- Write operations are **disabled by default**\n- Use HTTPS for production instances\n- Store API tokens securely (never commit to git)\n- Consider a dedicated BookStack user with limited permissions\n\n## Development\n\n```bash\nnpm run dev # Hot reload with tsx\nnpm run type-check # Type checking only\nnpm run build # Production build\n```\n\n## License\n\nMIT\n",
"bytes": 12628,
"sha": "4b4948887d0597910aee3106c332082896278ecfd6fac3e39c74e0f69145f13d",
"repo_slug": "ttpears/bookstack-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_ttpears_bookstack_mcp_304745c0/readme"
}