START_HERE.md•7.54 kB
# 🎉 Your BookStack MCP Server is Ready!
## What You Have Now
A complete **Python MCP Server** that connects Cursor AI to your BookStack instance at **http://192.168.1.193:6875**.
```
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Cursor │ ◄─MCP──►│ Python Server│ ◄─API──►│ BookStack │
│ AI │ │ (FastMCP) │ │ 192.168.1.193│
└─────────────┘ └──────────────┘ └──────────────┘
```
## 📁 What Was Installed
```
/home/borjigin/dev/bookstack-mcp/
│
├── 🔧 Core Server
│ ├── server.py Main MCP server (10 tools)
│ ├── requirements.txt Python dependencies
│ └── venv/ Virtual environment (ready)
│
├── 🚀 Launch Scripts
│ ├── run_server.sh Start the server
│ ├── test_connection.py Test BookStack connection
│ ├── setup_env.sh Create .env file
│ └── setup.sh Full automated setup
│
├── 📝 Configuration
│ ├── env.template Template for .env
│ ├── .env YOUR CREDENTIALS (create this!)
│ └── cursor-mcp-config.json Example Cursor config
│
└── 📚 Documentation
├── START_HERE.md ⭐ This file
├── NEXT_STEPS.txt Quick reference guide
├── QUICKSTART.md Fast 2-minute setup
├── README.md Complete manual
├── PROJECT_OVERVIEW.md Architecture details
└── INSTALLATION_SUMMARY.md What was installed
```
## 🎯 What to Do Next (2 Minutes)
### 1️⃣ Get API Token from BookStack
Open http://192.168.1.193:6875 → Login → Profile → API Tokens → Create Token
You'll get:
- **Token ID**: `abc123xyz...`
- **Token Secret**: `def456uvw...`
### 2️⃣ Configure Environment
```bash
cd /home/borjigin/dev/bookstack-mcp
./setup_env.sh
```
Or manually:
```bash
cp env.template .env
nano .env # Add your token ID and secret
```
### 3️⃣ Test Connection
```bash
./test_connection.py
```
Expected output:
```
✅ BookStack is reachable
✅ API authentication successful!
✅ Found X books in your BookStack
✅ All tests passed!
```
### 4️⃣ Add to Cursor
**Method 1: Using Settings File**
Edit `~/.config/cursor/mcp_settings.json`:
```json
{
"mcpServers": {
"bookstack": {
"command": "/home/borjigin/dev/bookstack-mcp/run_server.sh"
}
}
}
```
**Method 2: Using Cursor UI**
1. Open Cursor → Settings (Ctrl+,)
2. Search "MCP"
3. Add Server:
- Name: `bookstack`
- Command: `/home/borjigin/dev/bookstack-mcp/run_server.sh`
**Restart Cursor** after configuration!
### 5️⃣ Test in Cursor
Open a new chat and type:
```
"List all books in my BookStack"
```
If you see BookStack data, **you're done!** 🎉
## 🛠 Available Tools (10 Total)
Once configured, you can use these through natural language in Cursor:
### 📖 Discovery & Reading
- `bookstack_list_content` - List books, chapters, pages
- `bookstack_search` - Search all content
- `bookstack_get_page` - Read page content
### ✍️ Creating Content
- `bookstack_create_book` - Create new books
- `bookstack_create_chapter` - Create chapters
- `bookstack_create_page` - Create pages
### 🔧 Editing & Management
- `bookstack_update_page` - Update page content
- `bookstack_delete_page` - Delete pages
## 💬 Example Conversations with Cursor
Once set up, talk naturally:
**Browsing:**
- "Show me all books"
- "List pages in book 3"
- "Search for 'Docker' documentation"
- "Find pages about authentication"
**Creating:**
- "Create a book called 'DevOps Guide'"
- "Add a chapter 'Getting Started' to book 5"
- "Create a page about Kubernetes in chapter 2 with markdown content..."
**Reading:**
- "Show me page 42"
- "What's in the API documentation page?"
- "Read the content of book 3"
**Updating:**
- "Update page 15's title to 'New Title'"
- "Modify page 20 with this new content..."
## 📊 System Requirements
✅ **Python**: 3.12 (installed in venv)
✅ **FastMCP**: 2.13.1 (installed)
✅ **httpx**: 0.28.1 (installed)
✅ **python-dotenv**: 1.2.1 (installed)
✅ **BookStack**: Running at http://192.168.1.193:6875
⚠️ **API Token**: Need to create (Step 1 above)
⚠️ **.env file**: Need to configure (Step 2 above)
## 🔧 Quick Commands Reference
```bash
# Navigate to project
cd /home/borjigin/dev/bookstack-mcp
# Setup environment
./setup_env.sh
# Test connection
./test_connection.py
# Run server manually (for debugging)
./run_server.sh
# Or with venv
source venv/bin/activate
python server.py
# Check dependencies
pip list | grep -E "fastmcp|httpx|dotenv"
# Verify BookStack is reachable
curl http://192.168.1.193:6875
```
## 🐛 Troubleshooting
### "Cannot connect to BookStack"
```bash
# Test connectivity
curl http://192.168.1.193:6875
# If this fails, check:
# - Is BookStack container running?
# - Is it accessible on port 6875?
docker ps | grep bookstack
```
### "API authentication failed"
```bash
# Test API manually
curl -H "Authorization: Token YOUR_ID:YOUR_SECRET" \
http://192.168.1.193:6875/api/books
# If this fails:
# - Check token ID and secret are correct
# - Verify token has permissions
# - Try creating a new token
```
### "Permission denied" on scripts
```bash
chmod +x *.sh *.py
```
### "Module not found" errors
```bash
source venv/bin/activate
pip install -r requirements.txt
```
### Cursor doesn't show tools
1. Run `./test_connection.py` - must pass all tests
2. Check Cursor MCP settings are correct
3. Look at Cursor logs: Help → Toggle Developer Tools → Console
4. Restart Cursor **completely** (close all windows)
## 📚 Documentation Guide
| File | Purpose | When to Read |
|------|---------|--------------|
| `START_HERE.md` | This file | Right now! |
| `NEXT_STEPS.txt` | Quick reference | For copy/paste commands |
| `QUICKSTART.md` | 2-minute setup | When you want to start quickly |
| `README.md` | Complete manual | For detailed information |
| `PROJECT_OVERVIEW.md` | Architecture | Understanding how it works |
| `INSTALLATION_SUMMARY.md` | What's installed | Technical details |
## 🎓 Learning More
### About BookStack API
https://www.bookstackapp.com/docs/api/
### About MCP (Model Context Protocol)
https://modelcontextprotocol.io/
### About FastMCP
https://gofastmcp.com/
### About Cursor MCP Integration
https://docs.cursor.com/context/model-context-protocol
## ✨ What Makes This Special
✅ **Minimal** - Only essential dependencies
✅ **Secure** - Credentials stay local in .env
✅ **Fast** - Direct API access, no middleware
✅ **Natural** - Talk to Cursor about your docs naturally
✅ **Isolated** - Virtual environment prevents conflicts
✅ **Complete** - Full CRUD operations on BookStack
## 🚀 Ready to Start?
Run these three commands:
```bash
cd /home/borjigin/dev/bookstack-mcp
./setup_env.sh
./test_connection.py
```
Then configure Cursor and you're done!
---
**Need help?** Read `NEXT_STEPS.txt` or run `./test_connection.py` for diagnostics.
**Questions?** Check `README.md` for complete documentation.
**Want details?** See `PROJECT_OVERVIEW.md` for architecture.
🎉 **Happy documenting with Cursor + BookStack!**