entraadm-mcp

영어 | 日本語

Microsoft Entra ID 로그인 및 감사 로그 트리아지를 위한 MCP 서버입니다. 읽기 전용입니다.

공식 Microsoft MCP Server for Enterprise 대신 이 서버를 사용하는 이유

Microsoft는 Entra ID 데이터용 공식 MCP Server for Enterprise를 제공합니다. 이는 키보드 앞에서 대화형으로 작업하는 관리자에게 적합하며, 무인 트리아지 봇에는 적합하지 않습니다:

• 위임 인증만 지원. 공식 서버는 앱 전용(클라이언트 자격 증명) 인증을 지원하지 않으므로 서비스 계정 뒤에서 헤드리스로 실행할 수 없습니다. entraadm-mcp는 이러한 경우를 위해 설계되었습니다: 프로덕션에서는 앱 전용, 로컬 개발에서는 위임(az login) 폴백을 사용합니다.

• 일반 목적 Graph 쿼리 도구이지 고정된 도구 세트가 아님. 공식 서버는 모델이 Microsoft Graph에 대해 임의의 GET/스키마 검색 호출을 구성할 수 있는 하나의 도구를 노출합니다. 이는 사람에게는 유연하지만, 자동화된 트리아지 프로필에 대한 허용 목록 뒤에 두기에는 어색합니다. entraadm-mcp는 대신 7개의 고정된 읽기 전용 도구를 노출합니다.

• AADSTS 변환 없음. 로그인 실패는 원시 오류 코드로 반환되며, 트리아지에는 여전히 조회 테이블이 필요합니다. entraadm-mcp는 모든 로그인 실패에 해당 코드가 실제로 의미하는 바를 주석으로 추가합니다.

• 요청 간 집계 없음. Microsoft Graph 자체는 서버 측에서 status/errorCode에 대한 로그인 필터링을 지원하지 않으며, 기본 제공 암호 스프레이 뷰도 없습니다. signin_failure_stats는 클라이언트 측에서 집계하고 여러 고유 사용자에 대해 실패한 로그인이 있는 IP에 플래그를 지정합니다 — Entra의 계정별 스마트 잠금이 자체적으로 포착하지 못하는 패턴입니다.

Related MCP server: Microsoft Graph MCP Server

도구

모든 도구는 읽기 전용입니다. 쓰기 작업(계정 차단 해제, 암호 재설정, 세션 해지)은 이 서버의 범위를 벗어납니다.

인증 모델

설정된 환경 변수에 따라 선택되는 두 가지 인증 모드:

세 개의 앱 전용 변수 중 하나 또는 두 개만 설정하는 것은 구성 오류이며, 의도한 것과 다른 인증 모드로 조용히 폴백하는 대신 서버가 시작을 거부합니다.

필수 Graph 권한

누락된 권한은 도구를 중단시키지 않습니다. 해당 도구(또는 해당 필드)를 {"error": "...", "missing_permission": "..."}로 저하시키고, 필요한 역할이나 권한에 대한 사람이 읽을 수 있는 설명을 제공하므로 health_check와 다른 모든 도구는 전체 권한이 부여되기 전에도 계속 사용할 수 있습니다.

설정

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

구성

프로덕션/무인 사용을 위해 세 개의 앱 전용 변수를 설정하세요:

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

또는 세 개 모두 설정하지 않고 로컬 개발을 위해 먼저 az login을 실행하세요.

선택 사항:

# Default page cap for the log-scanning tools (1-50, default 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

사용법

Claude Code (플러그인)

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code (수동)

.mcp.json에 추가:

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

직접 실행

entraadm-mcp

CLI 옵션

참고

• 범위 계약. 페이지가 매겨진 Graph 컬렉션을 탐색하는 모든 결과는 해당 창이 완전히 스캔되지 않은 경우 capped 부울을 전달합니다 — 부분 스캔이 완전한 것처럼 보고되지 않습니다.

• found: false는 오류가 아닙니다. get_user와 get_user_auth_methods는 존재하지 않는 계정에 {"found": false, ...}로 응답하며 error 키가 아닙니다 — 오타가 있는 userPrincipalName이 이 서버가 고장난 것처럼 보이게 해서는 안 됩니다.

• 보존 기간. Entra ID P1은 로그인 및 디렉터리 감사 로그를 30일 동안 보존합니다. 그 이상의 창은 오류가 아닌 빈 결과를 반환합니다.

개발

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

라이브 스모크 테스트

uv run python scripts/smoke_test.py

읽기 전용, 페이로드 출력 없음(도구 이름/상태/행 수만), 그리고 제한적(작은 명시적 창/페이지 캡) — 여기서 테넌트에 쓰거나 하루 이상의 로그를 스캔하지 않습니다.

릴리스

이 저장소는 Conventional Commits로 구동되는 release-please를 사용합니다. feat:/fix: PR을 main에 병합하면 release-please가 릴리스 PR을 열거나(또는 업데이트)합니다. 해당 PR을 병합하면 릴리스 태그가 생성되고 게시 파이프라인(PyPI, MCP Registry)이 트리거됩니다.

라이선스

MIT