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 (: Direct HTTP/SSE server for standalone deployment

2. Stdio Transport (: 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)

Manual Installation

Option 2: LibreChat Integration

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

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:

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:

LibreChat Integration Configuration

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

LibreChat docker-compose.override.yml

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

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

Standalone Production

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

LibreChat Integration Commands

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:

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:

Content Discovery:

Write Operations (if enabled):

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)

Development

Project Structure

Type Checking

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