@iflow-mcp/ttpears-bookstack-mcp

v2.0.1

Published

14 days ago

Modern BookStack MCP server for local and remote deployments

Downloads

0High
0Medium
0Low

chatflowdev

qystart

mcp bookstack model-context-protocol librechat smithery

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 McpServer with registerTool() 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 .env file

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:

McpServer from @modelcontextprotocol/sdk/server/mcp.js
registerTool() 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