blok-berichtsheft
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@blok-berichtsheftadd activity for today: trained on API design, 1.5h"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-berichtsheftCredentials 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 listRegistering 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-mcpCodex 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 containingdate(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 callingset_departmentoradd_activitywith a department — never guess a code.set_department(date, department)— sets the week's "Abteilung/Sparte" field to a code returned bylist_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 viazod)report.js— page actions: read/write entries, day status, department, remarksbrowser.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 appearedeven 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 sameadd_activitycall; 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_activitytool 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.
Available Tools
6 toolsadd_activityA
Add a new Berichtsheft activity entry for a specific day. Reuses an empty row if one exists for that day, otherwise adds a new row. Optionally also sets that day's location and/or presence status.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-07-22. Must fall on a Mon-Fri. | |
| text | Yes | Description of the activity/task performed | |
| hours | No | Time spent, e.g. "1h:30min", "1:30", or "1,5" | |
| location | No | Where the day took place | |
| presence | No | Attendance status for the day | |
| department | No | Abteilung/Sparte code for the week. Call list_departments and confirm with the user first - do not guess a code. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavior. It reveals that empty rows are reused and that location/presence can be optionally set. However, it does not explain what happens if the date already has a full row, whether the activity is appended, or any side effects (e.g., overwriting existing data). More detail on mutation behavior and error states would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three clear, front-loaded sentences: purpose, key behavior (row reuse), and additional capabilities. No redundant words or filler. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns or confirms on success. It does not mention return values, error handling, or side effects beyond adding an entry. For a simple add operation, this is adequate but leaves the agent guessing about confirmation or error states. A brief note on expected response (e.g., 'Returns the created activity entry ID') would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about row reuse and optional location/presence setting, but does not enhance understanding of individual parameters (e.g., the format of 'hours' or the meaning of enum values) beyond what the schema already provides. The added value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Add a new Berichtsheft activity entry for a specific day.' It also explains row reuse, making it distinct from sibling tools like get_week (read-only) and set_day_status (status change). The verb 'add' plus specific resource 'activity entry' leaves no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (adding activity entries) but does not explicitly guide when to use this tool versus alternatives like set_day_status or set_department. For instance, it doesn't clarify that add_activity is for daily tasks while set_day_status handles overall attendance. The mention of optionally setting location/presence could cause confusion with set_day_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_weekA
Read the Berichtsheft (training log) entries for the week containing the given date, including each day's location, presence, logged activities with hours, and the week remarks.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Any date in the target week; defaults to the current week |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must reveal behavioral traits; it clearly states the tool reads data and details the returned fields (location, presence, activities, week remarks). Implicitly a read-only operation is indicated by 'Read'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence concisely states the action, resource, and returned data with no wasted words. Front-loaded with 'Read' aligns with best practices.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what the tool returns (daily location, presence, activities, week remarks). It lacks details on error handling or edge cases but is sufficient for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single 'date' parameter with a clear description. The tool description does not add new semantics beyond reiterating the date's role, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and clearly identifies the resource as 'Berichtsheft (training log) entries for the week'. It effectively distinguishes from sibling tools like add_activity or set_day_status, which are mutation-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Read' conveys its retrieval purpose, and sibling tool names imply different actions, but no explicit guidance is provided on when to choose this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_departmentsA
List the valid "Abteilung/Sparte" codes for this account (the same autocomplete list BLok itself offers). Call this and ask the user which one applies before calling set_department or add_activity with a department - do not guess a code.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Any date in the target week; defaults to the current week |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavioral traits. While it mentions the source ('same autocomplete list BLok itself offers'), it does not state that the operation is read-only or any side effects. The behavioral disclosure is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. Every part contributes meaning: purpose, source, and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is complete: it explains what it returns, why it exists, and how to use it with siblings. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with one parameter 'date' already described in the schema. The description adds no extra parameter information beyond what the schema provides, warranting a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' and clearly identifies the resource as 'valid "Abteilung/Sparte" codes for this account'. It distinguishes from sibling tools by mentioning its use with set_department and add_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call this tool and ask the user before using set_department or add_activity, and warns against guessing. Provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_day_statusA
Set the location and/or presence status for a specific day in the Berichtsheft, without adding an activity.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-07-22. Must fall on a Mon-Fri. | |
| location | No | Where the day took place | |
| presence | No | Attendance status for the day |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral transparency. It fails to disclose whether the tool overwrites existing status, if it creates a day entry if missing, or what side effects occur (e.g., impact on existing activities). This leaves an agent uncertain about safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and object, containing no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and high schema coverage, the description is adequate for basic understanding. However, missing details on preconditions (e.g., does the day need to exist?) and return values (no output schema) make it incomplete for robust agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are well-documented in the input schema. The description paraphrases the schema ('Set the location and/or presence status') without adding new meaning or constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set'), the resource ('location and/or presence status for a specific day in the Berichtsheft'), and explicitly distinguishes itself from adding an activity, which is a sibling tool name. This makes the purpose specific and avoids confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear exclusion ('without adding an activity'), which directly contrasts with the sibling 'add_activity'. However, it does not provide guidance on when to use this tool versus other siblings like 'set_department' or 'set_week_remarks', leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_departmentA
Set the "Abteilung/Sparte" field for the week containing the given date. Call list_departments first and confirm the code with the user rather than guessing.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-07-22. Must fall on a Mon-Fri. | |
| department | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals the tool sets a field for the whole week, but does not mention overwrite behavior, permissions, idempotency, or return value. This leaves important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. First sets purpose, second provides usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and moderate schema coverage, the description covers purpose and usage but lacks details on behavior when the field already exists, error conditions, and response format. Adequate but with notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only date has a description). The description adds context for department by referencing list_departments and user confirmation, but does not specify format or accepted values beyond 'code'. For a 2-param tool, the description partially compensates but lacks full semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the 'Abteilung/Sparte' field for a week. The verb 'Set' and resource 'field for the week containing the given date' are specific. It distinguishes from sibling tools like list_departments, get_week, and set_week_remarks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call list_departments first and confirm the code with the user, providing clear when-to-use and when-not-to-guess guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_week_remarksA
Set the free-text remarks ("Bemerkungen") for the week containing the given date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format, e.g. 2026-07-22. Must fall on a Mon-Fri. | |
| text | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It states 'Set' indicating mutation but does not disclose whether it overwrites existing remarks, requires authentication, or has any side effects. The term 'free-text' suggests no validation but is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Front-loads the purpose and constraints, earning its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with no output schema and two parameters, the description is nearly complete. It explains what the tool does and the meaning of parameters. However, it could mention the expected return (e.g., success status) and any prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only date described). The description adds context by calling the text 'free-text remarks' and clarifying that the date should be for the containing week. However, it does not explain the text parameter's length limits or formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'Set', the resource 'free-text remarks for the week', and the context 'containing the given date'. It distinguishes from siblings like get_week (read) and set_day_status (day-level) by specifying week-level remarks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for writing remarks, but it does not mention when not to use it or provide direct comparisons with sibling tools like add_activity or set_day_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v1.0.0- First observed
add_activity - First observed
get_week - First observed
list_departments - First observed
set_day_status - First observed
set_department - First observed
set_week_remarks
TDQS
Each tool targets a distinct operation: reading a week, adding an activity, setting day status, listing departments, setting department, and setting week remarks. There is no functional overlap.
All tools follow a consistent verb_noun pattern (e.g., get_week, add_activity, set_day_status), making the API intuitive and predictable.
With 6 tools, the server is well-scoped for managing a training log (Berichtsheft). Each tool serves a clear purpose without redundancy or deficiency.
The core workflow (read week, add activity, set status/department/remarks) is covered. However, there is no explicit update or delete operation for activities, which could be a minor gap.
Maintenance
Related MCP Connectors
An MCP server that provides access to Testiny projects, test cases and test runs
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceA MCP server that provides browser automation tools, allowing users to navigate websites, take screenshots, click elements, fill forms, and execute JavaScript through Playwright.82-
- AlicenseBqualityDmaintenanceA browser automation server providing Playwright capabilities for controlling web browsers, capturing screenshots, extracting content, and performing complex interactions through an MCP interface.6Apache 2.0
- FlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that provides browser automation capabilities via Playwright using Server-Sent Events (SSE). It enables clients to perform web operations and scraping through a containerized Docker environment.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that automates Playwright-based UI and API testing, supporting test case generation from requirements or API specs, and execution with detailed reports.171MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/j551n-ncloud/blok-berichtsheft-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server