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

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:

Edit .env and add your BookStack credentials:

3. Test the Server

Run the server directly to test:

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:

Or use a script wrapper:

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:

API Reference

BookStack API documentation: https://www.bookstackapp.com/docs/api/

License

This project is open source and available for modification and use.