README.md•5.37 kB
# BookStack MCP Server for Cursor
A minimal Python MCP (Model Context Protocol) server that allows Cursor AI to manage your BookStack documentation.
## Features
This server provides essential BookStack management tools:
- **List Content**: Browse books, bookshelves, chapters, and pages
- **Search**: Full-text search across all content
- **Page Management**: Create, read, update, and delete pages
- **Book Management**: Create new books
- **Chapter Management**: Create new chapters
## Prerequisites
- Python 3.8 or higher
- BookStack instance with API access
- BookStack API token (ID and Secret)
## Setup
### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Configure Environment
First, you need to create an API token in BookStack:
1. Log in to your BookStack instance at http://192.168.1.193:6875
2. Go to your profile → API Tokens
3. Create a new token with appropriate permissions
4. Copy the Token ID and Token Secret
Then create a `.env` file:
```bash
cp .env.example .env
```
Edit `.env` and add your BookStack credentials:
```env
BS_URL=http://192.168.1.193:6875
BS_TOKEN_ID=your_actual_token_id
BS_TOKEN_SECRET=your_actual_token_secret
```
### 3. Test the Server
Run the server directly to test:
```bash
python server.py
```
The server will start and listen for MCP protocol messages via stdio.
## Cursor Integration
To use this MCP server with Cursor, add it to your Cursor MCP settings:
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to **Features** → **Model Context Protocol**
3. Add a new server configuration:
```json
{
"mcpServers": {
"bookstack": {
"command": "python",
"args": ["/home/borjigin/dev/bookstack-mcp/server.py"],
"env": {
"BS_URL": "http://192.168.1.193:6875",
"BS_TOKEN_ID": "your_token_id",
"BS_TOKEN_SECRET": "your_token_secret"
}
}
}
}
```
Or use a script wrapper:
```json
{
"mcpServers": {
"bookstack": {
"command": "/home/borjigin/dev/bookstack-mcp/run_server.sh"
}
}
}
```
4. Restart Cursor
## Available Tools
Once configured, you can ask Cursor to interact with BookStack:
### Listing Content
- "List all books in BookStack"
- "Show me the chapters in book 5"
- "Find pages with 'API' in the name"
### Searching
- "Search for 'authentication' in BookStack"
- "Find documentation about Docker"
### Reading Content
- "Get the content of page 42"
- "Show me what's in page ID 10"
### Creating Content
- "Create a new book called 'API Documentation'"
- "Create a chapter named 'Getting Started' in book 5"
- "Create a page in book 3 with markdown content..."
### Updating Content
- "Update page 15 to change the title to 'New Title'"
- "Modify page 20's content with this markdown..."
### Deleting Content
- "Delete page 99"
## Tools Reference
### bookstack_list_content
List content entities (books, bookshelves, chapters, pages)
- `entity_type`: "books" | "bookshelves" | "chapters" | "pages"
- `count`: Number of items (default 20)
- `offset`: Pagination offset (default 0)
- `filter_name`: Filter by name substring
### bookstack_search
Search across all content
- `query`: Search query string
- `page`: Page number (default 1)
- `count`: Results per page (default 20)
### bookstack_get_page
Get page details and content
- `page_id`: Page ID
### bookstack_create_page
Create a new page
- `book_id`: Book ID (required)
- `name`: Page title (required)
- `html` or `markdown`: Content (one required)
- `chapter_id`: Optional chapter ID
- `tags`: Optional tags (format: "tag1=value1,tag2=value2")
### bookstack_update_page
Update an existing page
- `page_id`: Page ID (required)
- `name`: New title (optional)
- `html` or `markdown`: New content (optional)
- `tags`: Optional tags
### bookstack_delete_page
Delete a page
- `page_id`: Page ID (required)
### bookstack_create_book
Create a new book
- `name`: Book name (required)
- `description`: Optional description
- `tags`: Optional tags
### bookstack_create_chapter
Create a new chapter
- `book_id`: Book ID (required)
- `name`: Chapter name (required)
- `description`: Optional description
- `tags`: Optional tags
## Troubleshooting
### Connection Issues
If Cursor can't connect to BookStack:
1. Verify BookStack is running: `curl http://192.168.1.193:6875`
2. Check your API tokens are correct
3. Ensure the token has sufficient permissions
### Permission Issues
If you get 403 errors:
- Your API token may lack necessary permissions
- Create a new token with admin or appropriate role permissions
### Server Not Starting
If the Python server won't start:
- Check Python version: `python --version` (must be 3.8+)
- Verify dependencies: `pip list | grep fastmcp`
- Check for errors in the `.env` file
## Development
To extend this server with more tools:
1. Add new functions decorated with `@mcp.tool()`
2. Use the `BookStackClient` for API calls
3. Follow the pattern of existing tools
Example:
```python
@mcp.tool()
async def bookstack_custom_operation(param: str) -> str:
"""Your custom tool description"""
client = get_client()
result = await client.request("GET", f"endpoint/{param}")
return str(result)
```
## API Reference
BookStack API documentation: https://www.bookstackapp.com/docs/api/
## License
This project is open source and available for modification and use.