[](https://smithery.ai/server/@yellowgg2/mcp-bookstack)
npm install @mseep/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.
- 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:
``bash`
npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude
`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"
}
}
}
}
The server provides a tool called search_pages that can be used to search pages from BookStack.
Parameters:
- query (string): Query to search for pagespage
- Default: "" (empty string)
- (number): Page number to returncount
- Range: 1-10
- Default: 1
- (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
`
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
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"
}
}
}
}
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:
1. Make changes to src/app.ts
2. Rebuild:
`bash``
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.