jobsuche
Click on "Deploy 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., "@jobsuche find IT Ausbildung offers in Berlin and export them for LLM"
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.
hermes-jobsuche
An open-source Hermes Agent native v2 plugin, Antigravity CLI MCP plugin, and Python CLI suite (jobsuche) for searching, monitoring, scoring, and exporting Ausbildung offers from the Bundesagentur für Arbeit (Jobsuche — arbeitsagentur.de) into LLM-ready Markdown & JSON bundles.
Features
Triple-Surface Architecture:
Hermes Agent Standalone v2 Plugin (
plugin.yaml+__init__.py): Exposesjobsuche_search,jobsuche_monitor,jobsuche_export_llm, andjobsuche_statustools plus the bundledjobsucheskill.Antigravity CLI Plugin (
.agents/plugins/jobsuche/): Bundles a stdio JSON-RPC 2.0 MCP server (mcp_server.py) with 6 tools (jobsuche_search_ausbildung,jobsuche_fetch_offer_details,jobsuche_sync_and_export,jobsuche_list_offers,jobsuche_update_offer_status,jobsuche_auth_status),rules/AGENTS.md, andskills/jobsuche/SKILL.md.Standalone CLI (
jobsuche): 7 subcommands (search,sync,export,companies,status,login,otp-test) for terminal and cron workflows.
Fast Public REST API (
pc/v6/jobs+pc/v4/jobdetails):Queries
https://rest.arbeitsagentur.de/jobboerse/jobsuche-service/pc/v6/jobs(angebotsart=4for Ausbildung / Duales Studium) and fetches full descriptions frompc/v4/jobdetails/{base64(refnr)}with zero browser overhead and no BA account required.
SQLite Deduplication & Audit History (
db.py):Tracks seen
refnrIDs, groups offers by normalizedcompany_slug, logs field changes (title,start_date,city,status) inoffer_history, and preserves applicant triage states (new,shortlisted,drafted,applied,rejected,ignored) across re-syncs.
Relevance Scoring & LLM-Ready Exports (
sorter.py,exporter.py):Scores offers (
0–100) by technical keyword alignment (e.g., Linux, Debian, Netzwerk, Windows Server, Active Directory, Virtualisierung, Proxmox, Docker, Firewall, IT-Support), distance (km), and start date.Generates per-offer folders
exports/offers/<Company_Slug>__<RefNr>/{offer.md,offer.json}with 16 YAML frontmatter fields and 5 structured sections, plusexports/INDEX_FOR_LLM.mdandexports/companies_summary.jsonso AI agents can immediately draft tailored German Anschreiben and CVs.
Optional Playwright Enrichment & 6-Digit TOTP (
auth_otp.py,browser.py,portal_scraper.py):Supports
pyotp6-digit TOTP generation (with<3swindow rollover guard) and IMAP/CLI fallback,de-DEstealth browser context withstorage_state.jsonpersistence, and strict CAPTCHA safety (never attempts to solve/bypass CAPTCHAs; saves diagnostic screenshot + JSON and alerts the user).
Related MCP server: job-search-mcp
Repository Layout
.
├── .agents/
│ └── plugins/
│ └── jobsuche/ # Antigravity CLI plugin (MCP server + rules + skill)
│ ├── assets/logo.svg
│ ├── mcp_config.json
│ ├── mcp_server.py
│ ├── plugin.json
│ ├── rules/AGENTS.md
│ └── skills/jobsuche/SKILL.md
├── plugins/
│ └── hermes/
│ └── jobsuche/ # Hermes plugin mirror for local script installs
├── scripts/
│ ├── deploy_and_test_remote.sh # Remote SSH/rsync test runner
│ └── install_plugins.sh # Local installer for Antigravity & Hermes plugins
├── skills/
│ └── jobsuche/
│ └── SKILL.md # Bundled Hermes Agent skill
├── src/
│ └── jobsuche_pkg/
│ ├── __init__.py
│ ├── api_client.py # Jobsuche REST API v6/v4 client
│ ├── auth_otp.py # 6-digit TOTP (pyotp) + IMAP/CLI fallback
│ ├── browser.py # Playwright context manager & CAPTCHA guard
│ ├── cli.py # `jobsuche` CLI entrypoint
│ ├── config.py # Settings & environment configuration
│ ├── db.py # SQLite storage, history & company profiles
│ ├── exporter.py # LLM-ready Markdown + JSON exporter
│ ├── models.py # Pydantic domain models
│ ├── portal_scraper.py # Optional authenticated portal scraper
│ └── sorter.py # Relevance scoring, filtering & company grouping
├── tests/
│ ├── e2e/ # 4-tier opaque-box E2E test suite (158 tests)
│ ├── test_api_and_db.py
│ ├── test_otp.py
│ ├── test_plugins.py
│ └── test_sorter_exporter.py
├── .env.example
├── CHANGELOG.md
├── LICENSE
├── README.md
├── __init__.py # Root Hermes plugin entrypoint (register(ctx))
├── plugin.yaml # Root Hermes plugin manifest (v2 standalone)
└── pyproject.tomlInstallation
1. Hermes Agent Plugin
# Install directly from GitHub
hermes plugins install clockwork-dev/hermes-jobsuche --enable --yes-deps
# Validate & inspect tools
hermes plugins validate ~/.hermes/plugins/jobsuche --json
hermes plugins doctor --ci ~/.hermes/plugins/jobsuche2. Local Clone (Python CLI + Antigravity CLI + Hermes Agent)
git clone https://github.com/clockwork-dev/hermes-jobsuche.git
cd hermes-jobsuche
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e ".[dev]"
# Link/install both Antigravity CLI and Hermes Agent plugins into ~/
./scripts/install_plugins.shCLI Usage (jobsuche)
# Search Ausbildung offers (defaults: Fachinformatiker/in für Systemintegration, Aachen, 25 km)
.venv/bin/jobsuche search --was "Fachinformatiker/in für Systemintegration" --wo Aachen --umkreis 25
# Sync offers into SQLite (data/jobsuche.db) and export LLM bundles into exports/
.venv/bin/jobsuche sync --was "Fachinformatiker/in für Systemintegration" --wo Aachen --umkreis 25
.venv/bin/jobsuche export
# List grouped companies and highest-scoring offers
.venv/bin/jobsuche companies
# Update application status and notes
.venv/bin/jobsuche status 10000-1208214389-S shortlisted --notes "Linux, Windows Server, AD, Firewall, VPN"LLM Export Structure (exports/)
Running jobsuche sync + jobsuche export (or calling jobsuche_sync_and_export / jobsuche_export_llm) generates:
exports/INDEX_FOR_LLM.md— Ranked Markdown table of all active offers (score, status, company, city/distance, start date, matched skills, relative path tooffer.md).exports/companies_summary.json— Aggregated statistics per employer (company_slug,offer_count,max_score,avg_score,offers).exports/offers/<Company_Slug>__<RefNr>/offer.md— Token-optimized Markdown card with 16 YAML frontmatter keys (refnr,title,profession,company,plz,city,distance_km,start_date,contact_name,contact_email,contact_phone,apply_url,portal_url,score,matched_skills,status) and 5 structured sections for immediate Anschreiben generation.exports/offers/<Company_Slug>__<RefNr>/offer.json— Full normalized JSON payload.
Testing
.venv/bin/pytestLicense
Released under the MIT License.
Available Tools
6 toolsjobsuche_auth_statusA
Check Bundesagentur für Arbeit session state, credentials, and 6-digit TOTP generator readiness.
Inputs: test_totp.
jobsuche_fetch_offer_detailsC
Fetch full description, requirements, and employer contact details for a Jobsuche refnr.
Inputs: refnr (required), mode, persist.
jobsuche_list_offersB
List and filter tracked Ausbildung offers stored in SQLite.
Inputs: city, limit, status, company, +2 more.
jobsuche_search_ausbildungC
Search Bundesagentur für Arbeit (arbeitsagentur.de) for Ausbildung offers (default: Fachinformatiker/in für Systemintegration in Aachen, 25 km radius).
Inputs: wo, plz, was, mode, +4 more.
jobsuche_sync_and_exportB
Synchronize Ausbildung offers from Jobsuche API into SQLite, score and group by company, and export LLM-ready Markdown/JSON packages to exports/.
Inputs: wo, plz, was, limit, +4 more.
jobsuche_update_offer_statusB
Update an offer's application status (new, shortlisted, drafted, applied, rejected, ignored) and notes.
Inputs: refnr (required), status (required), notes, db_path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role: remote search (search_ausbildung), remote detail fetch (fetch_offer_details), local tracking queries (list_offers), and status mutation (update_offer_status). The main potential confusion is list_offers vs. search_ausbildung, but descriptions clearly signal local SQLite vs. live API, so misselection risk is low.
All tools share the jobsuche_ prefix and mostly follow verb_noun style (fetch_offer_details, list_offers, search_ausbildung, update_offer_status, sync_and_export). auth_status deviates as a noun phrase, and sync_and_export bundles two actions, but the pattern remains readable and predictable.
Six tools cover a focused workflow (auth, search, fetch, sync/export, list, update) without redundancy. It is slightly lean — no removal/pruning operation and no standalone scoring tool — but each tool earns its place for this niche pipeline.
The core lifecycle is covered: session auth, discovery via search, detail retrieval, local tracking, status mutation, and bulk export. Minor gaps exist (no delete/archive of tracked offers, no manual add, no separate rescore), but agents can work around them via update_offer_status (e.g., 'ignored').
Maintenance
Related MCP Connectors
JobsPipe — data pipeline of every job posting on the web. Search live, normalized job postings from 30+ ATS feeds and job boards for AI agents via MCP.
Job application tracker for developers - AI agents write over MCP, you review in a dashboard.
Job search and interview prep MCP. 15 tools, OAuth 2.1, cross-LLM. four-leaf.ai.
Greenhouse/Lever jobs via Apify MCP; needs your Apify token. Unofficial; Ondalith is AI-operated.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceSearches LinkedIn, Indeed, USAJobs, and Google Jobs from the command line, deduplicates across sources, and optionally finds hiring manager emails; also runs as an MCP server for AI agents.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that aggregates job listings from Remotive and Arbeitnow, with local SQLite caching, application tracking, and saved searches.66 npmMIT
- FlicenseAqualityDmaintenanceEnables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.20-
- AlicenseAqualityDmaintenanceA privacy-first MCP server for locally managing job, fellowship, and graduate-school applications. It offers tools for tracking application status, analyzing role fit, generating LaTeX CV/cover letters, interview prep, and discovering public jobs from ATS APIs.81MIT