mcp-bookstack

# BookStack MCP Server [](https://smithery.ai/server/@yellowgg2/mcp-bookstack) 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](https://smithery.ai/server/@yellowgg2/mcp-bookstack): ```bash npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude ``` ### Installing Manually 1. Clone the repository: ```bash git clone https://github.com/yellowgg2/mcp-bookstack.git cd mcp-bookstack ``` 2. Install dependencies: ```bash 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: ```bash npm run build ``` 5. Add to your MCP settings configuration file (location depends on your system): For VSCode Claude extension: ```json { "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: ```typescript 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: ```json // ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) // %APPDATA%\Claude\claude_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: ```bash 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.