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:

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:

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 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:

Settings → Roles → create a role with Access System API.
Settings → Users → create a user, assign that role.
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

nano /etc/bookstack-mcp/env

Minimum to get running with Claude Code only:

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

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:

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

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.

2.8 KiB Raw Blame History