# Quickstart (Proxmox / LXD container)

Full detail is in `README.md`. This is the short path.

## 0. Where to put this

Unzip **anywhere except `/opt/bookstack-mcp`** — that path is the install
*target*, and the installer overwrites it. `/opt/src` is a good home:

```bash
cd /opt/src                       # or wherever you unzipped
unzip bookstack-mcp.zip
cd bookstack-mcp
```

You should now be able to run this with no errors — all three paths must exist:

```bash
ls pyproject.toml bookstack_mcp/server.py deploy/lxc/install.sh
```

## 1. Install

Requires Debian 12+ or Ubuntu 24.04+ (Python 3.11 or newer).

```bash
bash deploy/lxc/install.sh
```

This creates the `bookstack-mcp` service user, a venv at
`/opt/bookstack-mcp/venv`, config at `/etc/bookstack-mcp/env`, and a systemd
unit. Re-run it any time to upgrade; your config file is preserved.

## 2. Get a BookStack API token

Your instance uses OIDC, so the service user never needs to log in:

1. Settings → Roles → create a role with **Access System API**.
2. Settings → Users → create a user, assign that role.
3. Edit that user as an admin → **API Tokens** section at the bottom →
   **Create Token**. Copy the Token ID and Token Secret.

If you have `OIDC_REMOVE_FROM_GROUPS=true`, do not log this user in via SSO —
group sync will strip the role. See README step 1.

## 3. Configure

```bash
nano /etc/bookstack-mcp/env
```

Minimum to get running with Claude Code only:

```ini
BOOKSTACK_URL=https://wiki.yourdomain.com
BOOKSTACK_TOKEN_ID=...
BOOKSTACK_TOKEN_SECRET=...
BOOKSTACK_READ_ONLY=true
MCP_AUTH_MODE=token
MCP_STATIC_TOKENS=<openssl rand -hex 32>
```

Add claude.ai later by switching to `MCP_AUTH_MODE=oidc+token` and filling in
the OIDC block — see `deploy/authelia/configuration.snippet.yml`.

## 4. Start

```bash
systemctl start bookstack-mcp
systemctl status bookstack-mcp
journalctl -u bookstack-mcp -f
```

Verify locally. A 401 with a `www-authenticate` header is the correct answer:

```bash
curl -i http://127.0.0.1:8080/mcp
```

## 5. Reverse proxy

Point `https://mcp.yourdomain.com` at this container on **port 8080**.

Three things that will otherwise cost you an evening:

- Proxy the **whole hostname**, not just `/mcp`. OAuth discovery lives at
  `/.well-known/*` on the domain root.
- **Disable buffering** (`proxy_buffering off`, long `proxy_read_timeout`).
  Streamable HTTP holds a stream open.
- **Bypass Authelia forward-auth** for this host. Claude can't hold session
  cookies; the MCP server does its own OAuth.

## 6. Connect

```bash
claude mcp add --transport http bookstack https://mcp.yourdomain.com/mcp \
  --header "Authorization: Bearer YOUR_STATIC_TOKEN" --scope user
```

For claude.ai: Settings → Connectors → Add custom connector →
`https://mcp.yourdomain.com/mcp`. Requires `MCP_AUTH_MODE=oidc+token`.