BookStack MCP Server
A modern Model Context Protocol (MCP) server for BookStack, providing AI assistants with full access to your BookStack documentation.
Features
- Modern MCP Implementation - Uses latest
McpServerwithregisterTool()API - Full BookStack API Integration - Search, read, create, and update content
- Embedded URLs - All responses include clickable links to BookStack pages
- Multiple Deployment Options - Local (stdio), LibreChat, or hosted (Smithery.ai)
- Comprehensive Tools - 17+ tools for BookStack operations
- Type-Safe - Full TypeScript with Zod schemas
- Security - Write operations disabled by default
Quick Start
Prerequisites
- Node.js 18+
- BookStack instance with API access
- BookStack API token (Token ID and Secret)
Installation
# Clone repository
git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your BookStack credentials
# Build
npm run build
# Run
npm start
Environment Variables
Create a .env file:
# Required
BOOKSTACK_BASE_URL=https://your-bookstack.com
BOOKSTACK_TOKEN_ID=your-token-id
BOOKSTACK_TOKEN_SECRET=your-token-secret
# Optional
BOOKSTACK_ENABLE_WRITE=false # Set to 'true' to enable write operations
Usage
Local Use (Claude Desktop)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"bookstack": {
"command": "node",
"args": ["/path/to/bookstack-mcp/dist/index.js"],
"env": {
"BOOKSTACK_BASE_URL": "https://your-bookstack.com",
"BOOKSTACK_TOKEN_ID": "your-token-id",
"BOOKSTACK_TOKEN_SECRET": "your-token-secret"
}
}
}
}
LibreChat Integration
Add to your librechat.yaml:
mcpServers:
bookstack:
command: npx
args:
- -y
- bookstack-mcp
env:
BOOKSTACK_BASE_URL: "https://your-bookstack.com"
BOOKSTACK_TOKEN_ID: "your-token-id"
BOOKSTACK_TOKEN_SECRET: "your-token-secret"
# BOOKSTACK_ENABLE_WRITE: "false" # Optional
Or use local build:
mcpServers:
bookstack:
command: node
args:
- /path/to/bookstack-mcp/dist/index.js
env:
BOOKSTACK_BASE_URL: "https://your-bookstack.com"
BOOKSTACK_TOKEN_ID: "your-token-id"
BOOKSTACK_TOKEN_SECRET: "your-token-secret"
NPM Package (Coming Soon)
npx bookstack-mcp
Remote Deployment (Smithery.ai)
Coming soon: bookstack-mcp.webmodule.org
Available Tools
Read Operations (Always Available)
- get_capabilities - Show current server capabilities
- search_content - Advanced search with filtering and pagination
- search_pages - Search specifically for pages with book filtering
- get_books - List books with advanced filtering and sorting
- get_book - Get detailed information about a specific book
- get_pages - List pages with previews and context
- get_page - Get full content of a specific page
- get_chapters - List chapters with filtering
- get_chapter - Get details of a specific chapter
- get_shelves - List book shelves (collections)
- get_shelf - Get shelf details with all books
- get_attachments - List attachments with filtering
- get_attachment - Get attachment details
- export_page - Export pages in various formats
- export_book - Export entire books
- export_chapter - Export chapters
- get_recent_changes - Get recently updated content
Write Operations (Requires BOOKSTACK_ENABLE_WRITE=true)
- create_page - Create new pages
- update_page - Update existing pages
- create_shelf - Create new shelves
- update_shelf - Update existing shelves
- delete_shelf - Delete shelves
- create_attachment - Create link attachments
- update_attachment - Update attachments
- delete_attachment - Delete attachments
BookStack API Setup
- Log into your BookStack instance as an admin
- Go to Settings → Users → Edit your user
- Ensure the user has "Access System API" permission
- Navigate to the "API Tokens" section
- Create a new API token
- Copy the Token ID and Token Secret to your
.envfile
Security Considerations
- Write operations are disabled by default for safety
- Only enable writes if you trust the AI with your BookStack content
- Use HTTPS for production BookStack instances
- Store API tokens securely (never commit to git)
- Consider using a dedicated BookStack user with limited permissions
- Regular token rotation recommended
Development
# Development with hot reload
npm run dev
# Type checking
npm run type-check
# Build for production
npm run build
Project Structure
src/
├── index.ts # Main server entry (MCP implementation)
├── bookstack-client.ts # BookStack API wrapper
└── bookstack-tools.ts # Legacy (no longer used)
dist/ # Compiled JavaScript output
Response Enhancements
All responses include:
- Direct URLs - Clickable links to BookStack pages
- Content Previews - 150-200 character excerpts
- Human-Friendly Dates - "2 hours ago" instead of timestamps
- Contextual Info - Book/chapter locations, word counts
- Rich Metadata - Creation dates, update history
Troubleshooting
Connection Issues
# Test BookStack API access
curl -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
https://your-bookstack.com/api/docs
LibreChat Issues
- Server not starting - Check environment variables in
librechat.yaml - Permission errors - Verify BookStack API user has correct permissions
- Tools not appearing - Restart LibreChat after config changes
Debug Mode
Check logs for error messages:
- LibreChat:
docker compose logs -f api - Local: Errors go to stderr
Architecture
Built with modern MCP patterns:
McpServerfrom@modelcontextprotocol/sdk/server/mcp.jsregisterTool()API with Zod schemas- Stdio transport for local/LibreChat use
- Single entry point (
src/index.ts) - Type-safe with TypeScript 5.3+
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test with LibreChat and Claude Desktop
- Submit a pull request
License
MIT License - see LICENSE file for details
Links
- Repository: https://github.com/ttpears/bookstack-mcp
- BookStack: https://www.bookstackapp.com
- MCP: https://modelcontextprotocol.io
- LibreChat: https://www.librechat.ai
- Smithery: https://smithery.ai