freehire MCP server

Ein MCP-Server über die freehire-Job-API. Er ermöglicht jedem MCP-Host – Claude Desktop, Claude Code oder einem kompatiblen Agenten – IT-Jobs zu suchen, zu filtern und sich zu bewerben, ohne Browser, mit Authentifizierung über einen persönlichen API-Schlüssel. Stellenausschreibungen werden direkt von den Karriereseiten der Unternehmen gecrawlt – 3.3M+ offene Rollen bei 294K Unternehmen, normalisiert in ein Schema und getaggt mit Stack, Seniorität, Region und Arbeitsmodell (Live-Zahlen).

Er spiegelt die freehire-CLI: gleiche API, gleiche Anmeldedaten, bereitgestellt als MCP-Tools statt Shell-Befehle.

Install

Keine globale Installation nötig – der Host führt es über npx aus. Fügen Sie es zur MCP-Konfiguration Ihres Hosts hinzu (Claude Desktop → Einstellungen → Entwickler → Konfiguration bearbeiten oder ~/.claude.json für Claude Code):

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

Erstellen Sie den fhk_…-Schlüssel in der Web-App (freehire.me → Kontomenü → API-Schlüssel). Wenn Sie bereits die freehire-CLI verwenden (freehire auth login), können Sie env weglassen – der Server liest dieselbe ~/.freehire/creds.json.

Related MCP server: job-monitor

Authentication

Das Token und die API-Basis-URL werden mit folgender Priorität aufgelöst: env → ~/.freehire/creds.json → Standard https://freehire.me:

Der Server liest nur die Credentials-Datei (er schreibt sie nie – das Einloggen bleibt Aufgabe der CLI). Wenn kein Token konfiguriert ist, geben die Tools einen klaren „nicht authentifiziert“-Fehler zurück, anstatt dass der Server nicht startet.

Tools

Filter. search, market_fit und facets teilen sich dieselben Marktfilter-Parameter: remote, region, country, city, company, category, role, seniority, employment_type, english_level, exclude_skill, salary_min, visa, plus eine generische facets-Map ({"source": "greenhouse"}) für jedes andere Facet im Vokabular. Entdecken Sie gültige Werte mit dem facets-Tool – erfinden Sie sie nicht. In search ist skills ein Filter; in market_fit ist skills die gemessene Menge.

Geografie erweitert. region, country und city sind eine ODER-Gruppe: region: ["eu"] mit country: ["IT"] bedeutet „in Europa oder in Italien“ und gibt alles zurück, was die Region allein auch tun würde. Um ein einzelnes Land zu suchen, übergeben Sie country und lassen region weg. Die drei benennen ein einziges Konzept – wo –, daher liest sich die Auswahl von zwei Orten als „entweder“, was region: ["eu"] mit country: ["BR"] („Europa oder Brasilien“) nützlich macht. Es gibt kein UND zum Einschalten: _mode=and gilt nicht für Geografie.

Unbekannte Parameter werden ignoriert, nicht abgelehnt. Ein Filter-Schlüssel, den die API nicht erkennt, lässt die Anfrage nicht fehlschlagen, sondern erweitert sie. Solche Schlüssel erscheinen in der ignored-Liste des Ergebnisses, mit did_you_mean, wenn nur die grammatische Zahl falsch war. search meldet es zusammen mit total; facets und market_fit antworten mit einem einzelnen Objekt, also verpacken sie es als {data, ignored} – und nur dann, sodass die Form eines sauberen Aufrufs unberührt bleibt. Jede Zahl aus einem Ergebnis mit ignored beantwortet eine breitere Frage als die gestellte – wiederholen Sie den Versuch mit dem vorgeschlagenen Namen, bevor Sie es melden.

Beschreibungen. search liest den Agent-Endpunkt der API, sodass jeder Treffer bereits die vollständige Beschreibung der Stelle als Markdown enthält – ein Host kann eine Ergebnismenge prüfen, ohne pro Treffer einen job-Aufruf zu machen. Beschreibungen sind lang, also halten Sie limit bescheiden.

Die Beweisregel. Jede Leistung in der Bank protokolliert, wer sie behauptet hat. cv_import, stated_in_chat und manual bedeuten, dass der Kandidat es getan hat, und dürfen in einem CV zitiert werden; agent_inferred bedeutet, dass ein Modell es in den Datensatz gelesen hat, und darf nicht zitiert werden. cv_edit lehnt jede Behauptung über den Kandidaten ohne eine evidence_id ab, die auf eine zitierbare verweist – deshalb ist experience_list das Tool, das cv_edit überhaupt erst nutzbar macht.

Das Korrigieren einer Leistung verschiebt dieses Label nicht: Eine agent_inferred-Leistung bleibt unzitierbar, egal wie sie umformuliert wird. Der einzige Weg, sie zitierbar zu machen, ist, den Kandidaten zu fragen und dann aufzuzeichnen, was sie sagen, mit experience_add_achievement.

Entfernen ist endgültig – die Bank hat kein Rückgängig. Ein Arbeitsplatz muss geleert werden, bevor er gelöscht werden kann, denn das Löschen würde jede darunter liegende Leistung mitnehmen. Das Zusammenführen zweier Leistungen zu einer, unter Beibehaltung der Zahlen beider, erfolgt auf der Website.

Jedes Tool gibt die rohen API-data als JSON-Text zurück; ein API-Fehler wird zu einem isError-Ergebnis mit dem HTTP-Status (eine 401 fügt einen Auth-Hinweis hinzu).

Develop

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

License

MIT – siehe LICENSE. Das freehire-Backend und die CLI sind ebenfalls MIT.