# 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.
