ARIM MCP-Server

Ein MCP-Server (stdio) zum direkten Abfragen von Messdaten, Statistiken, Korrekturen und Berichten des ARIM-Air-Monitoringsystems in Claude.

Nur lesend. Funktionen, die den Serverzustand verändern (Berichte veröffentlichen, Korrekturen anwenden, Gerätebefehle, Backfill, Alarme anlegen/löschen), sind nicht enthalten.

Installation

Node.js 18 oder höher ist erforderlich.

macOS / Linux

cd /Users/amdmania/Project/arimair-mcp
npm install
npm run build
./setup-arim-mcp.sh     # Claude Code + Claude Desktop 자동 등록

Windows

Legen Sie das Repository an einem beliebigen Ort ab (z. B. C:\Users\<Benutzer>\arimair-mcp) und führen Sie es in diesem Ordner aus. Das Installationsskript ermittelt Pfade relativ zu seinem eigenen Speicherort, funktioniert also unabhängig vom Ablageort.

In PowerShell:

cd C:\Users\<사용자>\arimair-mcp
npm install
npm run build
powershell -ExecutionPolicy Bypass -File .\setup-arim-mcp.ps1

-ExecutionPolicy Bypass erlaubt die Ausführung nicht signierter Skripte nur dieses eine Mal. Es ändert keine Systemrichtlinien.

Was das Installationsskript tut (allgemein)

Die Serveradresse ist fest auf den Produktionsserver (https://monitor.arimair.com) eingestellt und wird nicht abgefragt. Beide Skripte fragen nur nach Benutzername, Passwort und Kontotyp und registrieren sich anschließend an den folgenden beiden Orten.

• Claude Code CLI (claude mcp add arim -s user) — wird übersprungen, wenn der Befehl claude nicht vorhanden ist

• Claude-Desktop-Konfigurationsdatei — vorhandene Dateien werden als .bak.<Zeitstempel> gesichert, bereits registrierte andere MCP-Server bleiben erhalten

Nach der Registrierung muss Claude Desktop vollständig beendet und neu geöffnet werden, damit die Tools erscheinen.

Manuelle Registrierung

# macOS / Linux
claude mcp add arim -s user -t stdio \
  -e ARIM_API_BASE_URL=https://monitor.arimair.com \
  -e ARIM_MCP_USER=<아이디> \
  -e ARIM_MCP_PASS=<비밀번호> \
  -- node /Users/amdmania/Project/arimair-mcp/build/index.js

# Windows (PowerShell) — 경로는 실제 설치 위치로
claude mcp add arim -s user -t stdio `
  -e "ARIM_API_BASE_URL=https://monitor.arimair.com" `
  -e "ARIM_MCP_USER=<아이디>" `
  -e "ARIM_MCP_PASS=<비밀번호>" `
  -- node C:\Users\<사용자>\arimair-mcp\build\index.js

Wenn Sie kein Passwort registriert haben, melden Sie sich nach dem Verbinden mit dem Tool arim_login an.

Umgebungsvariablen

Wenn die Anmeldedaten als Umgebungsvariablen gesetzt sind, erfolgt beim ersten Toolaufruf eine automatische Anmeldung; bei abgelaufener Sitzung wird einmal neu angemeldet und erneut versucht.

Authentifizierungsmethode

Der ARIM-Server stellt kein JWT aus, sondern authentifiziert über HttpSession + Sitzungscookie (SESSION von Spring Session). Der MCP speichert das beim Aufruf von /account/login erhaltene Cookie und sendet es bei späteren Anfragen mit.

An alle Anfragen wird der Header X-Mcp-Client: 1 angehängt. Wenn dieser Header vorhanden ist, gibt der AuthorizeInterceptor des Servers statt einer 302-Weiterleitung auf die Anmeldeseite ein 401-JSON zurück. Der MCP wertet dies als Sitzungsablauf und meldet sich erneut an.

Standort

Alle Abfragen zu Messgeräten, Messdaten, Statistiken und Berichten beziehen sich auf den aktuell ausgewählten Standort. Intern ist es die monitorId (Administratorkonto des Überwachungsziels) der Sitzung, in den Tools wird es jedoch als „Standort" behandelt. Es entspricht dem Standort-Auswahlfeld oben im Web-Interface.

site_list                        → 선택 가능한 사이트와 현재 사이트
site_select { site: "울산 환경보건센터" }   → 사이트 변경

Bei site_select genügt ein Teil des Standortnamens. Auch wenn die Wortreihenfolge vom registrierten Namen abweicht (z. B. registrierter Name [환경보건센터] 울산 울산대), wird der Standort gefunden, solange alle Wörter enthalten sind. Gesucht wird im Anzeigenamen (company), im Namen des Verantwortlichen (name) und in der siteId.

• Bei mehreren Kandidaten wird nicht willkürlich einer ausgewählt, sondern eine Kandidatenliste zurückgegeben (z. B. „환경보건센터" → 9 Standorte)

• Ein exakter Namensabgleich hat Vorrang vor einer Teilübereinstimmung (z. B. „도로교통연구원" → arimsc_ex)

Benutzerkonten sehen nur freigegebene Anbieter, Administratorkonten die gesamte Liste (gleiche Regel wie im Web-Interface).

Werkzeugliste

Authentifizierung

Standort

Messgeräte

Messdaten

Statistik & Wetter

Korrektur

Berichte

Alarme

Überwachungsaggregation

Verarbeitung großer Antworten

Die Zeitreihen-Abfragewerkzeuge akzeptieren maxRows (Standard 500). Da der Server keine Obergrenze für die Zeilenzahl hat und bereits eine Tagesabfrage im Minutentakt über 1.400 Zeilen liefert, wird bei Überschreitung gleichmäßig abgetastet (Sampling) und die Antwort enthält zusätzlich totalRows / returnedRows / sampled. Die letzte (neueste) Zeile bleibt immer erhalten.

Serverseitige Abhängigkeiten

Dieser MCP setzt die folgenden Serveränderungen voraus.

Ohne /account/me und /setting/sensorlist funktionieren nur arim_whoami, sensor_list und alarm_config_list (wenn adminId weggelassen wird) nicht; alle übrigen Werkzeuge funktionieren normal. Auch site_list funktioniert, aber ohne /account/me kann der aktuelle Standort nicht beim Server angefragt werden; daher wird der in dieser Sitzung über site_select gewählte Wert als aktueller Standort angezeigt.

Die Standortfunktion selbst verwendet ohne Serveränderungen ausschließlich die vorhandenen APIs (/site/update/{id}, /admin/list, /datarequest/providerlist).