BookStack MCP Server

A Model Context Protocol (MCP) server that provides tools for searching pages from BookStack. This server interacts with the BookStack API and provides structured data for pages with clean HTML-to-text conversion.

Features

• Search pages from BookStack with customizable queries
• Get structured data including titles, URLs, and content
• Configurable pagination (page number and count)
• HTML-to-text conversion for clean content reading
• Clean error handling and validation

Installation

Installing via Smithery

To install mcp-bookstack for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude

Installing Manually

1. Clone the repository:

git clone https://github.com/yellowgg2/mcp-bookstack.git
cd mcp-bookstack

2. Install dependencies:

npm install

3. Configure your environment:

Create a .env file with your BookStack API credentials or provide them in the MCP settings configuration file:

BOOKSTACK_API_TOKEN=your_token
BOOKSTACK_API_URL=your_bookstack_url
BOOKSTACK_API_KEY=your_api_key

4. Build the server:

npm run build

5. Add to your MCP settings configuration file (location depends on your system):

For VSCode Claude extension:

{
  "mcpServers": {
    "bookstack": {
      "command": "node",
      "args": ["/path/to/mcp-bookstack/build/app.js"],
      "env": {
        "BOOKSTACK_API_URL": "your_bookstack_url",
        "BOOKSTACK_API_TOKEN": "your_token",
        "BOOKSTACK_API_KEY": "your_api_key"
      }
    }
  }
}

Usage

The server provides a tool called search_pages that can be used to search pages from BookStack.

Tool: search_pages

Parameters:

• query (string): Query to search for pages
  • Default: “” (empty string)
• page (number): Page number to return
  • Range: 1-10
  • Default: 1
• count (number): Number of pages to return
  • Range: 1-30
  • Default: 10

Example usage:

use_mcp_tool with:
server_name: "bookstack"
tool_name: "search_pages"
arguments: {
  "query": "knowledge base",
  "page": 1,
  "count": 5
}

Sample output:

# Page Title

Page content in plain text format...

Source: https://your-bookstack-url/page-url

Integrating with Claude

To use this MCP server with Claude, you’ll need to:

1. Have the Claude desktop app or VSCode Claude extension installed
2. Configure the MCP server in your settings
3. Use Claude’s natural language interface to interact with BookStack

Configuration

For the Claude desktop app, VSCode Claude extension, and Cursor, add the server configuration to:

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%Claudeclaude_desktop_config.json (Windows)
{
  "mcpServers": {
    "bookstack": {
      "command": "node",
      "args": ["/path/to/mcp-bookstack/build/app.js"],
      "env": {
        "BOOKSTACK_API_URL": "your_bookstack_url",
        "BOOKSTACK_API_TOKEN": "your_token",
        "BOOKSTACK_API_KEY": "your_api_key"
      }
    }
  }
}

Example Interactions

Once configured, you can interact with Claude using natural language to search BookStack pages. Examples:

• “Search for documentation about API usage in our BookStack knowledge base”
• “Find information about deployment in our internal docs”
• “Look up security guidelines in BookStack”

Claude will automatically use the appropriate parameters to search for the pages you want.

Page Response Structure

Each page response includes:

• Title of the page
• Full content of the page (converted from HTML to plain text)
• Source URL to the original page

The HTML-to-text conversion handles:

• HTML entity decoding
• Line breaks and paragraph formatting
• List items with bullet points
• Removal of HTML tags
• Whitespace normalization

Development

The server is built using:

• TypeScript
• Model Context Protocol SDK
• Axios for API requests
• Zod for data validation
• dotenv for environment configuration

To modify the server:

1. Make changes to src/app.ts
2. Rebuild:

npm run build

Error Handling

The server includes robust error handling for:

• API connection failures
• Authentication issues
• Invalid parameter values
• Data parsing errors

Errors are returned with appropriate error codes and descriptive messages.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this in your own projects.