# @h4sht/bookstack-mcp

<p align="center">
  <img src="https://raw.githubusercontent.com/BookStackApp/BookStack/development/public/icon.png" alt="BookStack" width="120" />
</p>

<p align="center">
  <strong>MCP server for BookStack</strong> — connect Claude Code, Codex, OpenCode and any AI assistant to your BookStack wiki.<br>
  <em>One command, zero config files, instant setup.</em>
</p>

<p align="center">
  <a href="https://github.com/h4sht/bookstack-mcp"><img src="https://img.shields.io/badge/github-h4sht%2Fbookstack--mcp-blue?logo=github" alt="GitHub repo"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License MIT"></a>
  <img src="https://img.shields.io/badge/tests-32%2F32-brightgreen" alt="Tests 32/32">
  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js" alt="Node >=18">
</p>

---

## 🚀 Claude Code

```bash
claude mcp add bookstack -- npx github:h4sht/bookstack-mcp
```

Claude Code will prompt you for:
- `BOOKSTACK_BASE_URL` — your BookStack API URL (e.g. `https://wiki.example.com/api`)
- `BOOKSTACK_API_TOKEN` — your API token (`token_id:token_secret`)

Or pass them directly:

```bash
claude mcp add bookstack \
  --env BOOKSTACK_BASE_URL=https://wiki.example.com/api \
  --env BOOKSTACK_API_TOKEN=token_id:token_secret \
  -- npx github:h4sht/bookstack-mcp
```

Then use `/mcp` inside Claude Code to verify it's connected ✔

---

## 🛠️ What you get (25 tools)

| Category | Tools |
|----------|-------|
| 📚 **Books** (6) | list, get, create, update, delete, export |
| 📑 **Chapters** (6) | list, get, create, update, delete, export |
| 📄 **Pages** (6) | list, get, create, update, delete, export |
| 📚 **Shelves** (5) | list, get, create, update, delete |
| 🔍 **Search** (1) | search across all content |
| ⚙️ **System** (1) | instance info |

All `export_*` tools support `markdown`, `html`, `pdf`, `plaintext`.

---

## ✍️ Markdown-powered

BookStack stores pages as HTML but accepts **Markdown input** through its API. This means Claude can create and edit wiki pages in its native format:

```
"Create a page about async Python in book 3"

→ bookstack_create_page({
    book_id: 3,
    name: "Async Python Guide",
    markdown: "# Async Python\n\n`asyncio` is Python's standard library..."
  })
```

Pages are also exported as Markdown, so Claude can read, analyze, and improve existing content.

---

## 📦 Setup for other AI assistants

### OpenAI Codex

```bash
codex mcp add bookstack \
  --env BOOKSTACK_BASE_URL=https://wiki.example.com/api \
  --env BOOKSTACK_API_TOKEN=id:secret \
  -- npx github:h4sht/bookstack-mcp
```

Or add this to `~/.codex/config.toml`:

```toml
[mcp_servers.bookstack]
command = "npx"
args = ["github:h4sht/bookstack-mcp"]

[mcp_servers.bookstack.env]
BOOKSTACK_BASE_URL = "https://wiki.example.com/api"
BOOKSTACK_API_TOKEN = "id:secret"
```

Verify with: `codex mcp list`

### OpenCode

```bash
opencode mcp add
# Select "local", then enter: npx github:h4sht/bookstack-mcp
```

Or add to `opencode.json`:

```jsonc
{
  "mcp": {
    "bookstack": {
      "type": "local",
      "command": ["npx", "github:h4sht/bookstack-mcp"],
      "enabled": true,
      "environment": {
        "BOOKSTACK_BASE_URL": "https://wiki.example.com/api",
        "BOOKSTACK_API_TOKEN": "id:secret"
      }
    }
  }
}
```

### Cline (VS Code)

Add to Cline MCP settings file:

```json
{
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["github:h4sht/bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://wiki.example.com/api",
        "BOOKSTACK_API_TOKEN": "id:secret"
      }
    }
  }
}
```

### Any MCP-compatible assistant (stdio)

The server command is always the same:

```bash
npx github:h4sht/bookstack-mcp
```

Set `BOOKSTACK_BASE_URL` and `BOOKSTACK_API_TOKEN` as environment variables.

---

## 🔧 Config reference

| Variable | Required | Description |
|----------|----------|-------------|
| `BOOKSTACK_BASE_URL` | Yes | Full URL including `/api` |
| `BOOKSTACK_API_TOKEN` | Yes | Format: `token_id:token_secret` |
| `BOOKSTACK_TIMEOUT` | No | Request timeout ms (default: `30000`) |

---

## 🔒 Security

- **4 auditable files** — read the whole source in 10 minutes
- **One dependency** — only `@modelcontextprotocol/sdk` (official Anthropic)
- **Native fetch()** — no HTTP libraries, no hidden requests
- **Stdio only** — no open ports, no network surface
- **Zero telemetry** — no analytics, no tracking, no calls home
- **Stderr logging** — never writes to stdout (MCP protocol integrity)

---

## 🧪 Tests

```bash
npm test   # 32 tests, all passing ✅
```

---

## 📁 Structure

```
@h4sht/bookstack-mcp/
├── src/
│   ├── index.ts      # MCP server, stdio transport, config
│   ├── client.ts     # BookStack REST client (native fetch)
│   ├── tools.ts      # 25 MCP tool definitions + handlers
│   └── types.ts      # TypeScript types
├── dist/             # Compiled JS (ready to run)
├── tests/            # 32 unit + integration tests
├── package.json
└── README.md
```

---

## 📝 License

MIT © [h4sht](https://github.com/h4sht)