BookStack MCP Server

A Model Context Protocol (MCP) server for BookStack with Server-Sent Events (SSE) support, designed for integration with LibreChat.

Features

• Full BookStack API Integration: Search, read, create, and update content
• Embedded URLs: All responses include clickable links to BookStack pages for immediate access
• Dual Transport Support: Both SSE and stdio transports available
• LibreChat Compatible: Self-contained Docker integration with supergateway
• Comprehensive Tools: 11 different tools for BookStack operations
• Authentication: Secure API token-based authentication
• TypeScript: Full type safety and modern development experience

Architecture

This server provides two different transport methods:

1. SSE Transport (src/index.ts): Direct HTTP/SSE server for standalone deployment
2. Stdio Transport (src/stdio.ts): MCP stdio server for use with supergateway in LibreChat

The LibreChat integration uses the stdio version with supergateway to bridge to HTTP/SSE automatically.

Available Tools

Read Operations (Always Available)

1. get_capabilities - Show current server capabilities and available tools
2. search_content - Advanced search with filtering, pagination, and BookStack search syntax
3. search_pages - Search specifically for pages with optional book filtering
4. get_books - List books with advanced filtering, sorting, and pagination
5. get_book - Get detailed information about a specific book
6. get_pages - List pages with filtering by book, chapter, custom criteria, and sorting
7. get_page - Get full content of a specific page
8. get_chapters - List chapters with advanced filtering options
9. get_chapter - Get details of a specific chapter
10. export_page - Export pages in various formats (HTML, PDF, Markdown, Plain text)

Write Operations (Requires BOOKSTACK_ENABLE_WRITE=true)

11. create_page - Create new pages in BookStack
12. update_page - Update existing pages

Security Note: Write operations are disabled by default. Set BOOKSTACK_ENABLE_WRITE=true to enable page creation and updates.

URL Integration: All responses include embedded URLs and direct links to BookStack content, making it easy to navigate from AI responses directly to the relevant pages for review or editing.

Installation

This server supports two deployment methods:

Option 1: Standalone Deployment

Docker (Recommended)

# Clone the repository
git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp

# Copy environment configuration
cp .env.example .env
# Edit .env with your BookStack configuration

# Build and run with Docker Compose
docker compose up -d

Manual Installation

# Clone the repository
git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

Option 2: LibreChat Integration

This method requires the Dockerfile.mcp-bookstack file in your LibreChat directory:

# 1. Copy Dockerfile.mcp-bookstack to your LibreChat root directory
# Download from: https://github.com/ttpears/bookstack-mcp/blob/main/Dockerfile.mcp-bookstack

# 2. Add environment variables to your LibreChat .env file (REQUIRED)
echo "BOOKSTACK_BASE_URL=https://your-bookstack.com" >> .env
echo "BOOKSTACK_TOKEN_ID=your-token-id" >> .env
echo "BOOKSTACK_TOKEN_SECRET=your-token-secret" >> .env

# 3. Update docker-compose.override.yml with the service configuration
# 4. Add MCP configuration to your librechat.yaml
# 5. Restart LibreChat
docker compose down && docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

Important: The Dockerfile.mcp-bookstack is self-contained and automatically clones the repository, builds the project, and configures supergateway during the Docker build process.

Configuration

Environment Variables

Create a .env file with the following variables:

# Required: BookStack Configuration
BOOKSTACK_BASE_URL=https://your-bookstack.com
BOOKSTACK_TOKEN_ID=your-token-id
BOOKSTACK_TOKEN_SECRET=your-token-secret

# Optional: Server Configuration
PORT=8007

# Optional: Security Configuration
BOOKSTACK_ENABLE_WRITE=false  # Set to 'true' to enable write operations

Important Security Notes:

• Write operations (create/update pages) are disabled by default
• Only enable writes if you fully trust the AI system with your BookStack content
• Consider using a dedicated BookStack user with limited permissions for API access

BookStack API Setup

1. Log into your BookStack instance as an admin
2. Go to Settings → Users → Edit your user
3. Ensure the user has "Access System API" permission
4. Navigate to the "API Tokens" section
5. Create a new API token with a descriptive name
6. Copy the Token ID and Token Secret to your .env file

Configuration

Standalone Configuration

For standalone deployment, add the following to your LibreChat librechat.yaml:

mcpServers:
  bookstack-mcp:
    url: http://localhost:8007/sse
    timeout: 60000

LibreChat Integration Configuration

For LibreChat integration, add the following to your librechat.yaml:

mcpServers:
  bookstack-mcp:
    type: sse
    url: http://bookstack-mcp:8007/sse

LibreChat docker-compose.override.yml

Add this service to your LibreChat docker-compose.override.yml:

services:
  bookstack-mcp:
    build:
      context: .
      dockerfile: Dockerfile.mcp-bookstack
    env_file:
      - .env
    ports:
      - "8007:8007"
    networks:
      - librechat
    restart: unless-stopped

Note: The LibreChat integration uses Dockerfile.mcp-bookstack which:

• Clones the repository directly (self-contained)
• Uses supergateway to bridge the stdio MCP server to HTTP/SSE
• Automatically handles the SSE endpoint creation

Usage

Standalone Development

# Start development server with hot reload
npm run dev

Standalone Production

# Build the project
npm run build

# Start production server
npm start

LibreChat Integration

Once integrated with LibreChat:

1. Start LibreChat with the new service:

   docker compose down && docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

2. Verify the BookStack MCP service is running:

   docker compose ps bookstack-mcp

3. Check service health:

   curl http://localhost:8007/health

Docker Commands

Standalone Docker Commands

# Build the Docker image
docker build -t bookstack-mcp .

# Run with Docker
docker run -d \
  --name bookstack-mcp \
  --env-file .env \
  -p 8007:8007 \
  bookstack-mcp

# Using Docker Compose (recommended)
docker compose up -d

# View logs
docker compose logs -f bookstack-mcp

# Stop the service
docker compose down

LibreChat Integration Commands

# Build and start LibreChat with BookStack MCP
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

# View BookStack MCP logs
docker compose logs -f bookstack-mcp

# Rebuild BookStack MCP service
docker compose build bookstack-mcp
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d bookstack-mcp

# Stop all services
docker compose down

API Endpoints

• GET /sse - SSE connection endpoint for LibreChat
• POST /message - Message routing for MCP protocol
• GET /health - Health check endpoint

Docker Deployment

The server is designed to run in Docker for easy deployment and scaling:

Features

• Multi-stage build for optimized image size
• Non-root user for security
• Health checks for container orchestration
• Proper signal handling for graceful shutdowns

Environment Variables in Docker

When using Docker, create a .env file in the project root:

BOOKSTACK_BASE_URL=https://your-bookstack.com
BOOKSTACK_TOKEN_ID=your-token-id
BOOKSTACK_TOKEN_SECRET=your-token-secret
PORT=8007

Production Considerations

For Both Deployment Methods

• Use Docker secrets or a secure secrets management system for API tokens
• Implement proper logging and monitoring
• Regular security updates for base images and dependencies

Standalone Production

• Consider running behind a reverse proxy (nginx, traefik)
• Use container orchestration (Docker Swarm, Kubernetes) for high availability
• Implement rate limiting and request throttling

LibreChat Integration Production

• Follow LibreChat's production deployment guidelines
• Ensure BookStack MCP service is included in backup/restore procedures
• Monitor resource usage as part of the LibreChat stack
• Consider using external networks for better isolation

Example Usage

In LibreChat Conversations

Once configured, you can use BookStack tools in LibreChat conversations:

Advanced Search Examples:

"Search for pages containing 'API authentication'"
"Find all pages in book 5 created this year"
"Search for content created by user ID 1"
"Show me the most recently updated pages in the Documentation book"

Content Discovery:

"List all books sorted by last updated"
"Show me pages in chapter 3 of the User Guide"
"Export page 456 as markdown"
"Get the content of the Installation Guide page"

Write Operations (if enabled):

"Create a new troubleshooting page in book 5"
"Update page 123 with the latest API changes"

Note: Write operations require BOOKSTACK_ENABLE_WRITE=true in your environment variables.

Production Usage:

• The AI can ask "What are my BookStack capabilities?" to see available tools
• All responses include clickable BookStack URLs for immediate access to content
• Write operations are disabled by default for security
• All read operations work without any special configuration
• Use the get_capabilities tool to understand current limitations

Direct API Testing (Standalone)

# Test health endpoint
curl http://localhost:8007/health

# Test SSE connection (will establish persistent connection)
curl -N http://localhost:8007/sse

Development

Project Structure

src/
├── bookstack-client.ts    # BookStack API client
├── bookstack-tools.ts     # MCP tools implementation  
├── sse-transport.ts       # SSE server transport
└── index.ts              # Main server entry point

Type Checking

npm run type-check

Security Considerations

• Always use HTTPS for production BookStack instances
• Store API tokens securely and rotate them regularly
• Consider implementing additional authentication for the MCP server in production
• Review BookStack user permissions to limit API access appropriately

Troubleshooting

Standalone Deployment Issues

1. Connection Issues:

   • Verify BookStack URL is accessible: curl https://your-bookstack.com/api/docs
   • Check API token permissions in BookStack
   • Verify server is running: curl http://localhost:8007/health

2. Permission Errors:

   • Ensure the BookStack user has "Access System API" permission
   • Verify API tokens are correctly configured in .env
   • Check that the user has appropriate permissions for the content being accessed

LibreChat Integration Issues

1. Service Not Starting:

   # Check if service is defined properly
   docker compose config bookstack-mcp
   
   # Check service logs
   docker compose logs bookstack-mcp

2. MCP Connection Issues:

   • Verify the service name in librechat.yaml matches the docker-compose service name
   • Check that the URL uses the internal Docker network: http://bookstack-mcp:8007/sse
   • Ensure environment variables are properly passed to the container

3. Environment Variable Issues:

   # Verify environment variables are loaded
   docker compose exec bookstack-mcp env | grep BOOKSTACK

4. Network Issues:

   # Test internal connectivity from LibreChat container
   docker compose exec api curl http://bookstack-mcp:8007/health

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with appropriate tests
4. Submit a pull request

Additional Documentation

• LibreChat Integration: See LIBRECHAT_INTEGRATION.md for detailed LibreChat setup instructions
• Configuration Examples: Check librechat.yaml.example and docker-compose.override.yml.example

License

MIT License - see LICENSE file for details