102 lines
2.8 KiB
Markdown
102 lines
2.8 KiB
Markdown
# 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`.
|