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:

Installing Manually

1. Clone the repository:

2. Install dependencies:

3. Configure your environment:

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

4. Build the server:

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

For VSCode Claude extension:

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:

Sample output:

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:

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:

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.