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
- Clone the repository:
git clone https://github.com/yellowgg2/mcp-bookstack.git
cd mcp-bookstack
- Install dependencies:
npm install
- 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
- Build the server:
npm run build
- 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:
- Have the Claude desktop app or VSCode Claude extension installed
- Configure the MCP server in your settings
- 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%\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:
- Make changes to
src/app.ts - 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.