# arbeitsagentur-mcp

MCP server for **customers** of the German Bundesagentur für Arbeit (Agentur für Arbeit / Jobcenter).

- **Live public data** (no login): Jobbörse search and job ads, Weiterbildungssuche (mein NOW / KURSNET),
  BERUFENET occupation profiles, Entgeltatlas salaries, Dienststellen finder.
- **Local case file** (SQLite, mode 0600, never leaves your machine): profile, applications /
  Eigenbemühungen with *Nachweis* export (Markdown/CSV), Vermittlungsvorschläge, appointments,
  correspondence with automatic Widerspruch deadlines, tasks, `overview` dashboard.
- **Deadline calculators**: Widerspruch (§ 84 SGG, § 37 SGB X incl. the 4-day rule since 2025),
  Arbeitsuchend-/Arbeitslosmeldung (§§ 38, 141 SGB III), generic periods with weekend/holiday shift
  for all Bundesländer, ALG duration (§ 147 SGB III).
- **Letter drafts**: Widerspruch, Akteneinsicht/DSGVO, Überprüfungsantrag, Veränderungsmitteilung,
  Terminabsage, Krankmeldung, Rückmeldung Vermittlungsvorschlag, Bildungsgutschein, Ortsabwesenheit.
- `rules` tool with short, sourced explanations of duties and sanctions.
- **Your own "Meine BA" account** (`meineba_*`): Postfach (read, download attachments, send after
  explicit confirmation), Termine, Verlauf, Antragsübersicht, Leistungen, Jobsuche watch list with
  notes and application status, saved searches.

General information, not legal advice.

## Meine BA login

You sign in yourself; the server never sees your password.

1. `meineba_login_start(service="postfach")` returns a link to `sso.arbeitsagentur.de`.
2. Open it in your own browser and sign in (password + second factor, passkey or BundID).
3. The browser lands on an arbeitsagentur.de page whose address contains `code=…&state=…` (the page
   itself may show an error; that's fine). Copy the full address within about a minute and pass it
   to `meineba_login_finish`.

This is the OpenID Connect authorization-code flow with PKCE that the BA web apps use. Each BA web
app is its own client (`postfach`, `termine`, `verlauf`, `antraege`, `leistungen`, `jobsuche`), so each
needs a login; after the first one your browser's single sign-on makes the others instant. Tokens are
stored in `meineba-tokens.json` next to the case file (mode 0600, override with
`ARBEITSAGENTUR_MCP_TOKENS`) and refreshed automatically; `meineba_logout` ends the sessions.

The endpoints are the ones the BA's own web apps call, not a documented API. They were mapped from
the apps' public JavaScript and checked to exist, and the client is tested against a simulated SSO
and API, but response formats can differ or change; responses are passed through mostly as-is.

## Usage

```sh
uv run arbeitsagentur-mcp            # stdio
claude mcp add arbeitsagentur -- uv --directory /path/to/arbeitsagentur-mcp run arbeitsagentur-mcp
```

Options: `--db PATH` (or `ARBEITSAGENTUR_MCP_DB`; default `~/.local/share/arbeitsagentur-mcp/akte.sqlite3`),
`--transport streamable-http --host 127.0.0.1 --port 8000`.

## Tests

```sh
uv run pytest            # offline
uv run pytest -m live    # against the real APIs
```

The public endpoints and client IDs are those used by the BA's own web apps (see bundesAPI on GitHub).
License: MIT.

## Nix packaging

`nix build` builds the `arbeitsagentur-mcp` executable and its Python runtime from
`uv.lock` using uv2nix. `nix run . -- --help` shows the CLI. No network access
is required when running the application build after its pinned inputs have
been fetched. `nix flake check` runs the offline test suite (56 tests at
introduction); live directory/API requests are excluded. Linux x86_64 and
aarch64 packages are defined; builds were verified on x86_64.

`nix develop` provides an editable Python environment plus uv. Run `pytest` or
`arbeitsagentur-mcp` directly there; changes under `src/` take effect immediately.
Run `uv lock` when changing Python dependencies and commit `uv.lock`; update
Nix inputs with `nix flake update` and commit `flake.lock`.

This project is a per-user stdio tool by default. It has no NixOS service module;
there is no public authenticated HTTP deployment. Private databases and user
configuration stay outside the Nix store and repository at the paths documented
above.