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

$3

To install mcp-bookstack for Claude Desktop automatically via Smithery:

``bash
npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude
`

$3

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

$3

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

$3

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"
}
}
}
}
`

$3

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.