BookStack MCP Server

A comprehensive Model Context Protocol (MCP) server providing full access to BookStack's knowledge management capabilities. This server exposes all 47 BookStack API endpoints as MCP tools, enabling seamless integration with Claude and other MCP-compatible AI assistants.

🚀 Features

$3

- 47 MCP Tools covering all BookStack API endpoints
- Resource Access for dynamic content retrieval
- Real-time Search across all content types
- Export Functionality in multiple formats (HTML, PDF, Markdown, Plain Text)
- Content Management for books, pages, chapters, shelves, users, and roles

$3

- Rate Limiting with configurable limits and burst protection
- Comprehensive Validation using Zod schemas
- Error Handling with retry logic and proper error mapping
- Context7 Integration for enhanced documentation
- Health Monitoring with detailed system checks
- Logging with configurable levels and formats

$3

- TypeScript Support with complete type definitions
- Hot Reloading during development
- Comprehensive Testing with unit and integration tests
- Docker Support for easy deployment
- Extensive Documentation with examples and guides

📦 Installation

$3

- Node.js 18+ and npm 9+
- BookStack instance with API access
- API token from BookStack

$3

1. Clone and Install
``bash git clone cd bookstack-mcp-server npm install`

2. Configure Environment`bash cp .env.example .env # Edit .env with your BookStack details`

3. Build and Start`bash npm run build npm start`

`$3`

Create a .env file with your BookStack configuration:

`env

`BookStack API Configuration`


BOOKSTACK_BASE_URL=http://localhost:8080/api
BOOKSTACK_API_TOKEN=your-api-token-here
BOOKSTACK_TIMEOUT=30000
Server Configuration

LOG_LEVEL=info
VALIDATION_ENABLED=true
CONTEXT7_ENABLED=true
Rate Limiting

RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_BURST_LIMIT=10


🛠️ Available Tools
$3

-

bookstack_books_list

 - List all books with filtering
-

bookstack_books_create

 - Create new books
-

bookstack_books_read

 - Get book details with contents
-

bookstack_books_update

 - Update book information
-

bookstack_books_delete

 - Delete books (to recycle bin)
-

bookstack_books_export

 - Export books in multiple formats
$3

-

bookstack_pages_list

 - List all pages with filtering
-

bookstack_pages_create

 - Create new pages with HTML/Markdown
-

bookstack_pages_read

 - Get page details with content
-

bookstack_pages_update

 - Update page content and metadata
-

bookstack_pages_delete

 - Delete pages (to recycle bin)
-

bookstack_pages_export

 - Export pages in multiple formats
$3

-

bookstack_chapters_list

 - List all chapters
-

bookstack_chapters_create

 - Create new chapters
-

bookstack_chapters_read

 - Get chapter details with pages
-

bookstack_chapters_update

 - Update chapter information
-

bookstack_chapters_delete

 - Delete chapters
-

bookstack_chapters_export

 - Export chapters
$3

- Search - Advanced search across all content
- Users & Roles - Complete user management
- Attachments & Images - File management
- Permissions - Content access control
- System Info - Instance information and health
- Recycle Bin - Deleted item recovery
🔗 Claude Code Integration
Add to your Claude Code MCP configuration:

`json { "mcpServers": { "bookstack": { "command": "npx", "args": ["bookstack-mcp-server"], "env": { "BOOKSTACK_BASE_URL": "http://localhost:8080/api", "BOOKSTACK_API_TOKEN": "your-token" } } } }`

`📚 Usage Examples`

`$3`

javascript
// Use the bookstack_books_list tool
{
  "count": 10,
  "sort": "updated_at",
  "filter": {
    "name": "documentation"
  }
}

$3

javascript
// Use the bookstack_pages_create tool
{
  "name": "API Documentation",
  "book_id": 1,
  "html": "API Guide
Complete API documentation...
",
  "tags": [
    {"name": "category", "value": "documentation"},
    {"name": "status", "value": "draft"}
  ]
}

$3

javascript
// Use the bookstack_search tool
{
  "query": "API documentation [page] tag:category=api",
  "count": 20
}


🧪 Development
$3

bash
npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Lint TypeScript code
npm run format       # Format code with Prettier

$3


src/
├── server.ts           # Main MCP server
├── api/
│   └── client.ts       # BookStack API client
├── tools/              # MCP tool implementations
│   ├── books.ts
│   ├── pages.ts
│   └── ...
├── resources/          # MCP resource handlers
├── utils/              # Utilities (logging, errors, rate limiting)
├── validation/         # Zod schemas and validation
├── config/             # Configuration management
└── context7/           # Context7 integration

$3

bash
Run all tests

npm test
Run specific test file

npm test books.test.ts
Run with coverage

npm run test:coverage


🐳 Docker Deployment
$3

bash
docker build -t bookstack-mcp-server .

$3

bash
docker run -p 3000:3000 \
  -e BOOKSTACK_BASE_URL=http://bookstack:8080/api \
  -e BOOKSTACK_API_TOKEN=your-token \
  bookstack-mcp-server

$3

yaml
version: '3.8'
services:
  bookstack-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      BOOKSTACK_BASE_URL: http://bookstack:8080/api
      BOOKSTACK_API_TOKEN: your-token
    depends_on:
      - bookstack


🔍 Monitoring & Health Checks
$3

The server provides health check functionality:

`bash curl http://localhost:3000/health`

Response:`json { "status": "healthy", "checks": [ {"name": "bookstack_connection", "healthy": true}, {"name": "tools_loaded", "healthy": true, "message": "47 tools loaded"}, {"name": "resources_loaded", "healthy": true, "message": "12 resources loaded"} ] }`

`$3`


- Request/response times
- Error rates
- Rate limit status
- Memory usage
- Tool usage statistics
🛡️ Security
$3

- Secure token storage in environment variables
- Token validation on startup
- Automatic token rotation support (when available)
$3

- Configurable request limits (default: 60/minute)
- Burst protection (default: 10 concurrent)
- Automatic backoff on rate limit hits
$3

- Comprehensive Zod schema validation
- SQL injection prevention
- XSS protection for HTML content
- File upload validation
🤝 Contributing

1. Fork the repository 2. Create a feature branch (git checkout -b feature/amazing-feature) 3. Commit your changes (git commit -m 'Add amazing feature') 4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

$3

- Follow TypeScript best practices
- Add tests for new features
- Update documentation
- Follow conventional commit messages
- Ensure all tests pass

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

- Documentation: Implementation Guide
- Issues: GitHub Issues
- Examples: Example Usage

🎯 Roadmap

$3

- [ ] Real-time notifications via WebSockets
- [ ] Bulk operations for content management
- [ ] Advanced caching strategies
- [ ] Metrics dashboard
- [ ] Plugin system for custom tools
- [ ] Multi-instance BookStack support

$3

- 99.9% uptime
- <100ms average response time
- Support for 1000+ concurrent connections
- Memory usage under 512MB

---

Built with ❤️ for the BookStack community

For more information about BookStack, visit bookstackapp.com

BookStack MCP Server

🚀 Features

$3

📦 Installation

$3

- Node.js 18+ and npm 9+
- BookStack instance with API access
- API token from BookStack

$3

1. Clone and Install
``bash git clone cd bookstack-mcp-server npm install`

2. Configure Environment`bash cp .env.example .env # Edit .env with your BookStack details`

3. Build and Start`bash npm run build npm start`

`$3`

Create a .env file with your BookStack configuration:

`env

`BookStack API Configuration`


BOOKSTACK_BASE_URL=http://localhost:8080/api
BOOKSTACK_API_TOKEN=your-api-token-here
BOOKSTACK_TIMEOUT=30000
Server Configuration

LOG_LEVEL=info
VALIDATION_ENABLED=true
CONTEXT7_ENABLED=true
Rate Limiting

RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_BURST_LIMIT=10


🛠️ Available Tools
$3

-

bookstack_books_list

 - List all books with filtering
-

bookstack_books_create

 - Create new books
-

bookstack_books_read

 - Get book details with contents
-

bookstack_books_update

 - Update book information
-

bookstack_books_delete

 - Delete books (to recycle bin)
-

bookstack_books_export

 - Export books in multiple formats
$3

-

bookstack_pages_list

 - List all pages with filtering
-

bookstack_pages_create

 - Create new pages with HTML/Markdown
-

bookstack_pages_read

 - Get page details with content
-

bookstack_pages_update

 - Update page content and metadata
-

bookstack_pages_delete

 - Delete pages (to recycle bin)
-

bookstack_pages_export

 - Export pages in multiple formats
$3

-

bookstack_chapters_list

 - List all chapters
-

bookstack_chapters_create

 - Create new chapters
-

bookstack_chapters_read

 - Get chapter details with pages
-

bookstack_chapters_update

 - Update chapter information
-

bookstack_chapters_delete

 - Delete chapters
-

bookstack_chapters_export

 - Export chapters
$3

- Search - Advanced search across all content
- Users & Roles - Complete user management
- Attachments & Images - File management
- Permissions - Content access control
- System Info - Instance information and health
- Recycle Bin - Deleted item recovery
🔗 Claude Code Integration
Add to your Claude Code MCP configuration:

`json { "mcpServers": { "bookstack": { "command": "npx", "args": ["bookstack-mcp-server"], "env": { "BOOKSTACK_BASE_URL": "http://localhost:8080/api", "BOOKSTACK_API_TOKEN": "your-token" } } } }`

`📚 Usage Examples`

`$3`

javascript
// Use the bookstack_books_list tool
{
  "count": 10,
  "sort": "updated_at",
  "filter": {
    "name": "documentation"
  }
}

$3

javascript
// Use the bookstack_pages_create tool
{
  "name": "API Documentation",
  "book_id": 1,
  "html": "API Guide
Complete API documentation...
",
  "tags": [
    {"name": "category", "value": "documentation"},
    {"name": "status", "value": "draft"}
  ]
}

$3

javascript
// Use the bookstack_search tool
{
  "query": "API documentation [page] tag:category=api",
  "count": 20
}


🧪 Development
$3

bash
npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Lint TypeScript code
npm run format       # Format code with Prettier

$3


src/
├── server.ts           # Main MCP server
├── api/
│   └── client.ts       # BookStack API client
├── tools/              # MCP tool implementations
│   ├── books.ts
│   ├── pages.ts
│   └── ...
├── resources/          # MCP resource handlers
├── utils/              # Utilities (logging, errors, rate limiting)
├── validation/         # Zod schemas and validation
├── config/             # Configuration management
└── context7/           # Context7 integration

$3

bash
Run all tests

npm test
Run specific test file

npm test books.test.ts
Run with coverage

npm run test:coverage


🐳 Docker Deployment
$3

bash
docker build -t bookstack-mcp-server .

$3

bash
docker run -p 3000:3000 \
  -e BOOKSTACK_BASE_URL=http://bookstack:8080/api \
  -e BOOKSTACK_API_TOKEN=your-token \
  bookstack-mcp-server

$3

yaml
version: '3.8'
services:
  bookstack-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      BOOKSTACK_BASE_URL: http://bookstack:8080/api
      BOOKSTACK_API_TOKEN: your-token
    depends_on:
      - bookstack


🔍 Monitoring & Health Checks
$3

The server provides health check functionality:

`bash curl http://localhost:3000/health`

`$3`


- Request/response times
- Error rates
- Rate limit status
- Memory usage
- Tool usage statistics
🛡️ Security
$3

- Secure token storage in environment variables
- Token validation on startup
- Automatic token rotation support (when available)
$3

- Configurable request limits (default: 60/minute)
- Burst protection (default: 10 concurrent)
- Automatic backoff on rate limit hits
$3

- Comprehensive Zod schema validation
- SQL injection prevention
- XSS protection for HTML content
- File upload validation
🤝 Contributing

$3

- Follow TypeScript best practices
- Add tests for new features
- Update documentation
- Follow conventional commit messages
- Ensure all tests pass

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

- Documentation: Implementation Guide
- Issues: GitHub Issues
- Examples: Example Usage

🎯 Roadmap

$3

- 99.9% uptime
- <100ms average response time
- Support for 1000+ concurrent connections
- Memory usage under 512MB

---

Built with ❤️ for the BookStack community

For more information about BookStack, visit bookstackapp.com