blok-berichtsheft MCP server

An MCP server that fills out your BLok Berichtsheft (Ausbildungsnachweis) via browser automation. BLok is an Apache Wicket app whose forms autosave per-field over AJAX (change for dropdowns, blur for text/number fields) — there's no public API, so this drives a real headless Chromium with Playwright instead of raw HTTP calls.

Setup

npm install
npx playwright install chromium
npm link                # exposes the `blok-berichtsheft-mcp` binary on PATH
cp .env.example .env    # then fill in your real credentials

.env is only used when running the server or scripts standalone (e.g. blok-berichtsheft-mcp directly). It is git-ignored — never commit it.

Related MCP server: Playwright Server MCP

Registering with Claude Code

claude mcp add blok-berichtsheft -s user \
  -e BLOK_USERNAME=your-username -e BLOK_PASSWORD=your-password \
  -- blok-berichtsheft-mcp

(or, without npm link, use -- node /absolute/path/to/index.js instead)

Check it's connected:

claude mcp get blok-berichtsheft

Credentials passed via -e are stored in ~/.claude.json, not in this project — that's what Claude Code actually uses at runtime. The .env file here is a separate, optional copy for local testing.

To remove: claude mcp remove blok-berichtsheft -s user

Registering with opencode

opencode has a native opencode mcp add command, but the simplest path is editing its config directly (~/.config/opencode/opencode.jsonc or opencode.json in a project) and adding an entry under mcp:

"mcp": {
  "blok-berichtsheft": {
    "type": "local",
    "command": ["blok-berichtsheft-mcp"],
    "environment": {
      "BLOK_USERNAME": "your-username",
      "BLOK_PASSWORD": "your-password"
    },
    "enabled": true
  }
}

(or "command": ["node", "/absolute/path/to/index.js"] without npm link)

Verify with:

opencode mcp list

Registering with Codex CLI

Codex CLI (codex, from OpenAI) configures MCP servers in ~/.codex/config.toml:

[mcp_servers.blok-berichtsheft]
command = "blok-berichtsheft-mcp"
env = { "BLOK_USERNAME" = "your-username", "BLOK_PASSWORD" = "your-password" }

(or command = "node", args = ["/absolute/path/to/index.js"] without npm link)

Recent Codex CLI versions also support codex mcp add, e.g.:

codex mcp add blok-berichtsheft \
  --env BLOK_USERNAME=your-username --env BLOK_PASSWORD=your-password \
  -- blok-berichtsheft-mcp

Codex CLI isn't installed on this machine, so this section is based on documented conventions rather than a locally verified run — check codex mcp --help / codex --help against your installed version if the exact flags differ.

Tools

All date parameters are YYYY-MM-DD and must fall on a Monday–Friday (BLok doesn't track weekends). Passing any date within a week navigates to that week automatically — past or future.

• get_week(date?) — reads the week containing date (defaults to the current week): each day's location, presence, activities (text + hours), the week's department and remarks.

• add_activity(date, text, hours?, location?, presence?, department?) — adds an activity entry for a day. Reuses an empty row for that day if one exists, otherwise adds a new row.

• set_day_status(date, location?, presence?) — sets a day's location/presence without adding an activity.

• list_departments(date?) — returns the account's actual valid "Abteilung/Sparte" codes (read live from the account's own autocomplete list). Call this and ask the user which one applies before calling set_department or add_activity with a department — never guess a code.

• set_department(date, department) — sets the week's "Abteilung/Sparte" field to a code returned by list_departments.

• set_week_remarks(date, text) — sets the week's free-text "Bemerkungen".

location is one of berufsschule, ausbildungsbetrieb, ueberbetrieblich. presence is one of anwesend, arbeitsunfaehig, abwesend, urlaub, sonderurlaub, feiertag. hours accepts any format BLok itself accepts: "1h:30min", "1:30", or "1,5".

What it deliberately does not do

None of these tools touch "Freigeben zur Abnahme durch Ausbilder" — submitting a week for trainer approval stays a manual, in-app action.

Files

• index.js — MCP server entry point, tool definitions (schemas via zod)

• report.js — page actions: read/write entries, day status, department, remarks

• browser.js — login, session reuse, and week navigation (parses the "Kalenderwoche vom … bis …" banner and clicks the week-forward/backward links until it lands on the target week)

Known quirk

The "Abteilung/Sparte" field is a jQuery UI autocomplete widget. Do not send Escape to close its suggestion menu after typing — jQuery UI's default Escape handler reverts the field to its prior value, which silently discards the edit before the save fires. Just blur the field (e.g. Tab).

Known issues

• Adding a brand-new row can occasionally throw Clicked "Zeile hinzufügen" but no new activity row appeared even though the row is added server-side a moment later — BLok's AJAX response for that specific action is sometimes slower than the fixed wait this checks against. Safe to just retry the same add_activity call; it will reuse the now-existing empty row instead of adding another one.

• No delete/remove tool yet. BLok's UI does support deleting a row (a "Zeile löschen" link sits next to each activity row), so this is addable, but no remove_activity tool exists in this version.

• BLok also disables editing for weeks too far in the future (somewhere between 4 and 7 weeks ahead, in testing) — not a bug in this tool, just BLok's own limit on how far in advance you can log entries.