ARIM MCP 서버

아림에어 모니터링 시스템의 측정 데이터·통계·보정·리포트를 Claude에서 직접 조회하는 MCP(stdio) 서버.

조회 전용입니다. 서버 상태를 바꾸는 기능(리포트 발행, 보정 적용, 디바이스 명령, 백필, 알람 등록/삭제)은 포함하지 않습니다.

설치

Node.js 18 이상이 필요합니다.

macOS / Linux

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

Windows

저장소를 원하는 위치(예: C:\Users\<사용자>\arimair-mcp)에 두고, 그 폴더에서 실행합니다. 설치 스크립트는 자기 위치를 기준으로 경로를 잡으므로 어디에 두든 그대로 동작합니다.

PowerShell에서:

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

-ExecutionPolicy Bypass는 서명되지 않은 스크립트 실행을 이번 한 번만 허용하는 옵션입니다. 시스템 정책을 바꾸지 않습니다.

설치 스크립트가 하는 일 (공통)

서버 주소는 운영 서버(https://monitor.arimair.com)로 고정되어 있어 묻지 않습니다. 두 스크립트 모두 아이디·비밀번호·계정 유형만 물어본 뒤 아래 두 곳에 등록합니다.

• Claude Code CLI (claude mcp add arim -s user) — claude 명령이 없으면 건너뜁니다

• Claude Desktop 설정 파일 — 기존 파일은 .bak.<타임스탬프>로 백업하고, 이미 등록된 다른 MCP 서버는 보존합니다

등록 후 Claude Desktop을 완전히 종료했다가 다시 열어야 도구가 나타납니다.

수동 등록

# 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/<사용자>/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

비밀번호를 등록하지 않았다면 연결 후 arim_login 도구로 로그인하면 됩니다.

환경 변수

자격증명을 환경변수로 넣어두면 첫 도구 호출 시 자동 로그인하고, 세션이 만료되면 한 번 재로그인 후 재시도합니다.

인증 방식

ARIM 서버는 JWT를 발급하지 않고 HttpSession + 세션 쿠키(Spring Session 의 SESSION)로 인증합니다. MCP는 /account/login 호출로 받은 쿠키를 보관해 이후 요청에 실어 보냅니다.

모든 요청에 X-Mcp-Client: 1 헤더를 붙입니다. 서버의 AuthorizeInterceptor는 이 헤더가 있으면 로그인 페이지로 302 리다이렉트하는 대신 401 JSON을 돌려주며, MCP는 이를 세션 만료로 판단해 재로그인합니다.

사이트

측정기·측정데이터·통계·리포트 조회는 모두 현재 선택된 사이트를 기준으로 합니다. 서버 내부적으로는 세션의 monitorId(모니터링 대상 관리자 계정)이지만, 도구에서는 "사이트"로 다룹니다. 웹 화면 상단의 사이트 선택 콤보와 같은 것입니다.

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

site_select는 사이트 이름 일부만 줘도 됩니다. 등록된 이름과 말하는 순서가 달라도(예: 등록명은 [환경보건센터] 울산 울산대) 낱말이 모두 들어 있으면 찾습니다. 표시명(company)과 담당자명(name), siteId 모두를 대상으로 검색합니다.

• 후보가 여럿이면 임의로 고르지 않고 후보 목록을 돌려줍니다 (예: "환경보건센터" → 9곳)

• 정확한 이름이 있으면 부분일치보다 우선합니다 (예: "도로교통연구원" → arimsc_ex)

일반사용자 계정은 승인받은 공급자만, 관리자 계정은 전체 목록을 봅니다 (웹 화면과 동일한 규칙).

도구 목록

인증

사이트

측정기

측정 데이터

통계·기상

보정

리포트

알람

모니터링 집계

대량 응답 처리

시계열 조회 도구는 maxRows(기본 500)를 받습니다. 서버는 행 수 상한이 없어 1일치 분단위 조회만으로도 1,400행 이상이 나오므로, 초과 시 균등 간격 샘플링하고 응답에 totalRows / returnedRows / sampled를 함께 돌려줍니다. 마지막(최신) 행은 항상 보존합니다.

서버 측 의존 사항

이 MCP는 아래 서버 변경을 전제로 합니다.

/account/me, /setting/sensorlist가 없으면 arim_whoami, sensor_list, alarm_config_list(adminId 생략 시)만 동작하지 않고 나머지 도구는 정상 동작합니다. site_list도 동작하지만, /account/me가 없으면 현재 사이트를 서버에 물어볼 수 없어 이 세션에서 site_select로 고른 값을 현재 사이트로 표시합니다.

사이트 기능 자체는 서버 수정 없이 기존 API(/site/update/{id}, /admin/list, /datarequest/providerlist)만 씁니다.