BookStack MCP Server

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