EntraID MCP 서버(Microsoft Graph FastMCP)

이 프로젝트는 Microsoft Graph API와 상호 작용하기 위한 모듈식 리소스 지향 FastMCP 서버를 제공합니다. 확장성, 유지 관리 용이성 및 보안을 고려하여 설계되었으며, 사용자, 로그인 로그, MFA 상태 및 권한 있는 사용자에 대한 고급 쿼리를 지원합니다.

특징

• 모듈형 리소스 구조:

  • 각 리소스(사용자, 로그인 로그, MFA 등)는 src/msgraph_mcp_server/resources/ 아래의 자체 모듈에서 구현됩니다.

  • 새로운 리소스(예: 그룹, 장치)로 쉽게 확장할 수 있습니다.

• 중앙 집중형 그래프 클라이언트:

  • 인증 및 클라이언트 초기화를 처리합니다.

  • 모든 리소스 모듈에서 공유됩니다.

• 포괄적인 사용자 운영:

  • 이름/이메일로 사용자를 검색합니다.

  • ID로 사용자를 가져옵니다.

  • 모든 권한이 있는 사용자(디렉토리 역할 구성원)를 나열합니다.

• 전체 그룹 수명 주기 및 멤버십 관리:

  • 그룹을 만들고, 읽고, 업데이트하고, 삭제합니다.

  • 그룹 구성원 및 소유자를 추가/제거합니다.

  • 그룹과 그룹 구성원을 검색하고 나열합니다.

• 애플리케이션 및 서비스 주요 관리:

  • 애플리케이션(앱 등록)을 나열, 생성, 업데이트 및 삭제합니다.

  • 서비스 주체를 나열, 생성, 업데이트 및 삭제합니다.

  • 애플리케이션과 서비스 주체 모두에 대한 앱 역할 할당과 위임된 권한을 확인합니다.

• 로그인 로그 작업:

  • 지난 X일간 사용자의 로그인 로그를 쿼리합니다.

• MFA 운영:

  • 사용자의 MFA 상태를 가져옵니다.

  • 그룹의 모든 구성원에 대한 MFA 상태를 가져옵니다.

• 비밀번호 관리:

  • 사용자 지정 또는 자동 생성된 보안 비밀번호를 사용하여 사용자 비밀번호를 직접 재설정합니다.

  • 다음 로그인 시 비밀번호 변경을 요구하는 옵션입니다.

• 권한 도우미:

  • 일반적인 작업에 적합한 Microsoft Graph 권한을 제안합니다.

  • 사용 가능한 Graph 권한을 검색하고 살펴보세요.

  • 필요한 권한만 권장하여 최소 권한의 원칙을 구현하는 데 도움이 됩니다.

• 오류 처리 및 로깅:

  • FastMCP 컨텍스트를 통해 일관된 오류 처리 및 진행 상황 보고가 가능합니다.

  • 문제 해결을 위한 자세한 로깅.

• 보안:

  • .env 및 secret 파일은 버전 제어에서 제외됩니다.

  • 인증을 위해 Microsoft 모범 사례를 사용합니다.

Related MCP server: Cloud PC Management MCP Server

프로젝트 구조

지엑스피1

용법

1. 설정

• 저장소를 복제합니다.

• Azure AD 자격 증명으로 config/.env 파일을 만듭니다.

  TENANT_ID=your-tenant-id CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret

• (선택 사항) 필요한 경우 인증서 기반 인증을 설정합니다.

2. 테스트 및 개발

FastMCP CLI를 사용하여 MCP 서버를 직접 테스트하고 개발할 수 있습니다.

MCP Inspector를 사용하여 대화형 개발 환경이 시작됩니다. 자세한 내용과 고급 사용법은 FastMCP 설명서를 참조하세요.

3. 사용 가능한 도구

사용자 도구

• search_users(query, ctx, limit=10) — 이름/이메일로 사용자 검색

• get_user_by_id(user_id, ctx) — ID로 사용자 세부 정보 가져오기

• get_privileged_users(ctx) — 권한이 있는 디렉토리 역할의 모든 사용자를 나열합니다.

• get_user_roles(user_id, ctx) — 사용자에게 할당된 모든 디렉토리 역할을 가져옵니다.

• get_user_groups(user_id, ctx) — 사용자의 모든 그룹(전환 멤버십 포함)을 가져옵니다.

그룹 도구

• get_all_groups(ctx, limit=100) — 모든 그룹 가져오기(페이징 포함)

• get_group_by_id(group_id, ctx) — ID로 특정 그룹을 가져옵니다.

• search_groups_by_name(name, ctx, limit=50) — 표시 이름으로 그룹 검색

• get_group_members(group_id, ctx, limit=100) — 그룹 ID로 그룹 구성원 가져오기

• create_group(ctx, group_data) — 새 그룹을 만듭니다(group_data 필드에 대해서는 아래 참조).

• update_group(group_id, ctx, group_data) — 기존 그룹 업데이트(필드: displayName, mailNickname, description, visibility)

• delete_group(group_id, ctx) — ID로 그룹 삭제

• add_group_member(group_id, member_id, ctx) — 그룹에 멤버(사용자, 그룹, 장치 등)를 추가합니다.

• remove_group_member(group_id, member_id, ctx) — 그룹에서 멤버를 제거합니다.

• add_group_owner(group_id, owner_id, ctx) — 그룹에 소유자 추가

• remove_group_owner(group_id, owner_id, ctx) — 그룹에서 소유자를 제거합니다.

그룹 생성/업데이트 예:

• create_group 및 update_group 에 대한 group_data 다음과 같은 키가 있는 사전이어야 합니다.

  • displayName (생성에 필요)

  • mailNickname (생성에 필요)

  • description (선택 사항)

  • groupTypes (선택 사항, 예: ["Unified"] )

  • mailEnabled (선택 사항)

  • securityEnabled (선택 사항)

  • visibility (선택 사항, "비공개" 또는 "공개")

  • owners (선택 사항, 사용자 ID 목록)

  • members (선택 사항, ID 목록)

  • membershipRule (동적 그룹에 필요)

  • membershipRuleProcessingState (선택 사항, "켜짐" 또는 "일시 중지됨")

지원되는 필드와 동작에 대한 자세한 내용은 groups.py docstring을 참조하세요.

로그인 로그 도구

• get_user_sign_ins(user_id, ctx, days=7) — 사용자의 로그인 로그를 가져옵니다.

MFA 도구

• get_user_mfa_status(user_id, ctx) — 사용자의 MFA 상태 가져오기

• get_group_mfa_status(group_id, ctx) — 모든 그룹 구성원의 MFA 상태를 가져옵니다.

장치 도구

• get_all_managed_devices(filter_os=None) — 모든 관리 장치 가져오기(선택적으로 OS로 필터링)

• get_managed_devices_by_user(user_id) — 특정 사용자에 대한 모든 관리 장치를 가져옵니다.

조건부 액세스 정책 도구

• get_conditional_access_policies(ctx) — 모든 조건부 액세스 정책 가져오기

• get_conditional_access_policy_by_id(policy_id, ctx) — ID로 단일 조건부 액세스 정책을 가져옵니다.

감사 로그 도구

• get_user_audit_logs(user_id, days=30) — 지난 N일 동안 user_id를 기준으로 해당 사용자의 모든 관련 디렉토리 감사 로그를 가져옵니다.

비밀번호 관리 도구

• reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — 특정 암호 값으로 사용자 암호를 재설정하거나 안전한 임의 암호를 생성합니다.

권한 도우미 도구

• suggest_permissions_for_task(task_category, task_name) — 공통 매핑을 기반으로 특정 작업에 대한 Microsoft Graph 권한 제안

• list_permission_categories_and_tasks() — 권한 제안에 사용 가능한 모든 카테고리와 작업을 나열합니다.

• get_all_graph_permissions() — Microsoft Graph API에서 직접 모든 Microsoft Graph 권한을 가져옵니다.

• search_permissions(search_term, permission_type=None) — 키워드로 Microsoft Graph 권한 검색

응용 프로그램 도구

• list_applications(ctx, limit=100) — 페이징을 사용하여 테넌트의 모든 애플리케이션(앱 등록)을 나열합니다.

• get_application_by_id(app_id, ctx) — 개체 ID로 특정 애플리케이션을 가져옵니다(앱 역할 할당 및 위임된 권한 포함)

• create_application(ctx, app_data) — 새 애플리케이션을 만듭니다(app_data 필드에 대해서는 아래 참조).

• update_application(app_id, ctx, app_data) — 기존 애플리케이션 업데이트(필드: displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)

• delete_application(app_id, ctx) — 개체 ID로 애플리케이션을 삭제합니다.

애플리케이션 생성/업데이트 예:

• create_application 과 update_application 에 대한 app_data 다음과 같은 키를 가진 사전이어야 합니다.

  • displayName (생성에 필요)

  • signInAudience (선택 사항)

  • tags (선택 사항)

  • identifierUris (선택 사항)

  • web (선택 사항)

  • api (선택 사항)

  • requiredResourceAccess (선택 사항)

서비스 주체 도구

• list_service_principals(ctx, limit=100) — 페이징을 사용하여 테넌트의 모든 서비스 주체를 나열합니다.

• get_service_principal_by_id(sp_id, ctx) — 개체 ID로 특정 서비스 주체를 가져옵니다(앱 역할 할당 및 위임된 권한 포함)

• create_service_principal(ctx, sp_data) — 새 서비스 주체를 만듭니다(sp_data 필드에 대해서는 아래 참조).

• update_service_principal(sp_id, ctx, sp_data) — 기존 서비스 주체 업데이트(필드: displayName, accountEnabled, tags, appRoleAssignmentRequired)

• delete_service_principal(sp_id, ctx) — 개체 ID로 서비스 주체를 삭제합니다.

서비스 주체 생성/업데이트 예:

• create_service_principal 및 update_service_principal 에 대한 sp_data 다음과 같은 키가 있는 사전이어야 합니다.

  • appId (생성에 필요)

  • accountEnabled (선택 사항)

  • tags (선택 사항)

  • appRoleAssignmentRequired (선택 사항)

  • displayName (선택 사항)

예시 리소스

• greeting://{name} — 개인화된 인사말을 반환합니다.

서버 확장

• resources/ 아래에 새로운 리소스 모듈을 추가합니다(예: groups.py , devices.py ).

• FastMCP @mcp.tool() 데코레이터를 사용하여 server.py 에 새로운 도구를 등록합니다.

• 모든 API 호출에 공유 GraphClient 사용합니다.

보안 및 모범 사례

• 비밀은 절대 커밋하지 마세요: .env 및 기타 민감한 파일은 git에서 무시됩니다.

• 최소 권한 사용: Azure AD 앱에 필요한 Microsoft Graph 권한만 부여합니다.

• 감사 및 모니터링: 로깅 출력을 사용하여 문제 해결 및 모니터링을 수행합니다.

필수 Graph API 권한

참고: Group.ReadWrite.All 그룹 생성, 업데이트, 삭제, 그리고 그룹 구성원이나 소유자 추가/제거에 필요합니다. Group.Read.All 과 GroupMember.Read.All 은 읽기 전용 그룹 및 멤버십 쿼리에 충분합니다.

고급: Claude 또는 Cursor와 함께 사용

클로드(인류학)와 함께 사용

이 서버를 Claude MCP 도구로 설치하고 실행하려면 다음을 사용하세요.

• /path/to/ 실제 프로젝트 경로로 바꾸세요.

• -f 플래그는 .env 파일을 가리킵니다(비밀을 커밋하지 마세요!).

커서와 함께 사용

.cursor/mcp.json 에 다음을 추가합니다(버전 제어에 실제 비밀을 포함하지 마세요 ).

• /path/to/ 와 환경 변수를 실제 값으로 바꾸세요.

• 실제 비밀을 저장소에 절대 저장하지 마세요!

특허

MIT