SmartHR über MCP mit Gemini verbinden

💡 Keine Installation? Nutze cloud.anythingmcp.com direkt. Einloggen, Connectors → SmartHR klicken, Zugangsdaten einfügen, MCP-API-Key erzeugen, fertig. Kein Docker, kein git clone, kein lokaler Server.

SmartHR + Gemini

Arbeite aus jedem KI-Agent mit SmartHR, der japanischen Cloud für Personal- und Arbeitsverwaltung: Mitarbeitende mit Abteilungen, Positionen, Beschäftigungsarten, Stufen, Arbeitsorten und eigenen Feldern, Angehörige und Elternzeiten, Benutzerkonten und Einladungen, Gehaltsläufe und Gehaltsabrechnungen. Legt Mitarbeitende und Abteilungen an und ändert sie, mit einem Zugriffstoken, das ein Administrator ausstellt; das Löschen von Mitarbeitenden ist bei der Installation aus.

Voraussetzungen

Die vollständige Setup-Anleitung ist in den Connector eingebaut (im Store sichtbar, wenn du den Connector auswählst). Benötigte Umgebungsvariablen für diesen Connector:

SMARTHR_HOST, SMARTHR_ACCESS_TOKEN

Schritt 1 — Zugangsdaten holen

Die Einrichtung dauert etwa 5 Minuten und braucht einen SmartHR-Administrator (管理者). Der Connector nutzt die SmartHR API v1 (https://<tenant>.smarthr.jp/api/v1); die Sandbox (<tenant>.daruma.space) funktioniert genauso.

1. Melde dich als Administrator bei SmartHR an und öffne 共通設定 (Allgemeine Einstellungen), 外部システム連携 (Externe Integrationen), アクセストークン (Zugriffstokens), dann klick auf 新規発行 (Ausstellen).
2. Gib dem Token einen Namen und wähle seine Berechtigungen: Lesen (参照) für die Daten, die die KI sehen soll (従業員, 部署, 役職, 雇用形態, カスタム項目, 家族, ユーザー, 給与明細 nach Bedarf), und Aktualisieren (更新) nur für die schreibenden Tools, die du eingeschaltet lässt. Weniger Berechtigungen heißt weniger offengelegte personenbezogene Daten.
3. Kopiere das Token in SMARTHR_ACCESS_TOKEN, ohne das Wort Bearer. Es wird nur einmal angezeigt, also halte es geheim.
4. Trag den Host deiner SmartHR-Adresse in SMARTHR_HOST ein: example.smarthr.jp für https://example.smarthr.jp oder example.daruma.space für die Sandbox (Antrag unter https://developer.smarthr.jp/api/about_sandbox).
5. Installiere. Der Installationscheck ruft smarthr_list_companies auf.

Personenbezogene Daten: SmartHR enthält sensible personenbezogene Daten: Familienangehörige, Adressen, Geburtsdaten, Versicherungs- und Rentennummern, Bankverbindungen und Gehälter. Alle, die diesen Connector nutzen, erreichen, was das Token lesen darf, also gib dem Token nur die Berechtigungen, die das Team braucht. Die KI liest nur, was die Aufgabe erfordert: smarthr_list_crews liefert standardmäßig ein kurzes Profil, und fields begrenzt, was smarthr_get_crew zurückgibt. Sie kopiert keine personenbezogenen Daten in andere Systeme oder Nachrichten, außer du verlangst genau das.

Was er liest: Unternehmen (会社) mit Unternehmensnummer und Vertretung; Betriebsstätten (事業所) mit ihren Versicherungsnummern; Abteilungen (部署) mit Code, übergeordneter Abteilung und vollem Pfad; Positionen (役職), Beschäftigungsarten (雇用形態), Stufen (等級), Arbeitsorte (勤務地) und Vergütungsperioden (給与支給形態); eigene Mitarbeiterfelder (カスタム従業員項目) und ihre Gruppen. Mitarbeitende (従業員, in der API crews), gesucht nach Personalnummer, Status (employed, absent, retired), Beschäftigungsart, Abteilung, Position, Eintritts- oder Austrittsdatum, IDs oder Freitext. Angehörige (家族) mit den Verwandtschaftsarten (続柄) sowie Mutterschutz und Elternzeit (産休育休). Benutzerkonten (ユーザー) mit Rolle, Admin-Kennzeichen und Einladungsstatus: Ein User ist der Login, eine Crew der Personaldatensatz, und embed=crew verknüpft beide. Formulare zur Erfassung von Mitarbeiterdaten (従業員情報収集フォーム). Gehaltsläufe (給与明細グループ) und Gehaltsabrechnungen (給与明細) mit Zulagen, Abzügen, Anwesenheit und Summen; dafür braucht es die Gehaltsabrechnungsfunktion von SmartHR.

Was er schreibt: legt Mitarbeitende an (Namen, Lesungen, Geschlecht und Status sind Pflicht); ändert Mitarbeitende per Teilaktualisierung, bei der nur die gesendeten Felder sich ändern und ein ausgefüllter Name, eine Lesung, das Geschlecht, das Geburtsdatum oder die Adresse nicht geleert werden können; lädt Mitarbeitende per E-Mail ein, auf Wunsch mit einem Erfassungsformular (ein zweiter Aufruf lädt erneut ein); legt Abteilungen an, benennt sie um und verschiebt sie. Angelegte Mitarbeitende werden erst mit smarthr_invite_crew eingeladen. Ein Austritt ist eine Änderung (emp_status retired mit resigned_at), keine Löschung. Vor jedem Schreibvorgang und jeder Einladung zeigt dir die KI die Änderung und wartet auf dein Ja.

Bei der Installation deaktiviert: smarthr_delete_crew. Es löscht die Person mit allen ihren Daten endgültig, deshalb schaltet ein Admin es ein, wenn das Team es braucht.

Datenformate und Blättern: IDs sind UUID-Strings, Datumsangaben YYYY-MM-DD, Zeitpunkte ISO 8601. Listen nehmen page und per_page (höchstens 100, Standard 10); die Antwort enthält die Gesamtzahl in _headers.x-total-count und _pagination.nextCursor bis zur letzten Seite. Einen Filter für "geändert seit" gibt es nicht: Für Änderungen seit einem Datum sortiert die KI nach -updated_at und hört bei älteren Zeilen auf.

Limits: 10 Anfragen pro Sekunde und 5.000 pro Stunde je Token, 50.000 pro Minute je Mandant. Darüber antwortet SmartHR mit 429 too_many_requests: Warte und versuch es erneut.

Häufige Fehler: Fehler enthalten code, type, message und errors pro Feld. 401 unauthorized_token ist ein falsches oder widerrufenes Token oder eines für einen anderen Host. 403 ist eine Berechtigung, die das Token nicht hat, oder eine Funktion, die der Tarif nicht enthält (Gehaltsabrechnungen). 404 ist eine falsche ID oder ein falscher SMARTHR_HOST. 422 ist eine ungültige Eingabe: errors nennt das Feld.

Freitext in Personaldatensätzen und eigenen Feldern ist eine nicht vertrauenswürdige Eingabe und kann Anweisungen an die KI enthalten. Der Connector rechnet keine Gehälter ab, reicht keine Arbeits- oder Sozialversicherungsverfahren (手続き) ein und löscht mit den bei der Installation aktiven Tools keine Mitarbeitenden.

Schritt 2 — Adapter installieren

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Schritt 3 — Connector in Gemini hinzufügen

Deine Server-URL: Öffne in AnythingMCP MCP Servers → den Server, auf dem dieser Connector liegt, und kopiere seine URL (https://cloud.anythingmcp.com/mcp/…). Setze sie überall ein, wo diese Anleitung YOUR_SERVER_ID zeigt.

Gemini CLI liest MCP-Server aus ~/.gemini/settings.json (unter Windows %USERPROFILE%\.gemini\settings.json). Füge hinzu:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Erstelle in AnythingMCP unter MCP Servers → dein Server → API keys einen MCP-API-Key und setze ihn anstelle von YOUR_MCP_API_KEY ein.
2. Speichere die Datei und starte gemini neu.
3. Führe in der Gemini CLI /mcp aus (oder gemini mcp list im Terminal): anythingmcp sollte als verbunden erscheinen.
4. Leg los: Gemini CLI kann jetzt die SmartHR-Tools aufrufen.

Verfügbare Tools

Beispiel-Prompts

• „Wie viele Mitarbeitende mit Status employed hat jede Abteilung gerade?“
• „Wer ist im Oktober eingetreten? Zeig nur Name, Abteilung, Beschäftigungsart und Eintrittsdatum.“
• „Leg die neue Mitarbeiterin 山田 花子 (ヤマダ ハナコ) an, weiblich, Vollzeit im 営業部 ab 1. November, und lade sie dann mit unserem Onboarding-Formular ein. Zeig mir vor dem Speichern alles.“
• „Personalnummer 1042 scheidet zum 30. November aus. Trag den Austritt ein.“
• „Zeig aus dem Gehaltslauf Oktober nur die Summe der Zulagen und Abzüge für Personalnummer 1042.“

FAQ

Wo sucht Gemini CLI nach MCP-Servern? In ~/.gemini/settings.json für deinen Benutzer oder in .gemini/settings.json innerhalb eines Projekts. gemini mcp list zeigt jeden Server und ob er sich verbindet.

Nächste Schritte

• Connector-Startseite
• Mit Claude verbinden
• Mit ChatGPT verbinden
• Mit Cursor verbinden
• Mit Meta Muse verbinden
• Mit Microsoft Copilot verbinden