lborjigi/bookstack-mcp

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

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:

cp .env.example .env

Edit .env and add your BookStack credentials:

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:

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:

{
  "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:

{
  "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:

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