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.
- 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
To install mcp-bookstack for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude
- 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"
}
}
}
}
The server provides a tool called search_pages
that can be used to search pages from BookStack.
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
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
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"
}
}
}
}
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.
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
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
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.
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - feel free to use this in your own projects.