Windows MCP Server (mcp-windows-ad)

Windows Server의 핵심 기능(Active Directory, DNS, 그룹 정책(GPO), 이벤트 로그)을 제어하고 조회할 수 있는 Model Context Protocol (MCP) 서버입니다. PowerShell을 기반으로 동작합니다.

필수 요구 사항

• 실행 환경: Windows Server 또는 RSAT가 설치된 Windows PC (로컬 실행 시)
  • 원격(WinRM) 실행 시: 외부 PC(Windows/Mac/Linux 상관없이 Node.js 환경에서)에서 AD 서버로 접속 가능. 단 대상 서버의 WinRM(5985/5986 포트) 개방 필수.
• PowerShell 모듈: 타겟 서버에 ActiveDirectory, DnsServer, GroupPolicy 모듈이 설치되어 있어야 합니다.
• 권한: 대상 서버에 대한 관리자 권한 (Domain Admin 등)

기능 (MCP Tools)

1. Active Directory 관리 (사용자, 헬프데스크, 그룹, 객체)

• windows_ad_list_users: AD 사용자 목록 및 상세 속성 조회
• windows_ad_create_user: 신규 AD 사용자 생성 (이름, UPN, 초기 비밀번호, OU 경로 등)
• windows_ad_update_user: 사용자 속성(부서, 직함, 관리자 등) 일괄 수정
• windows_ad_manage_user: 사용자 활성화, 비활성화, 삭제 등 상태 제어
• windows_ad_unlock_account: 잠긴(LockedOut) 계정 잠금 해제
• windows_ad_reset_password: 비밀번호 초기화 및 다음 로그인 시 강제 변경 설정
• windows_ad_create_ou: 신규 조직 단위(OU) 생성
• windows_ad_list_ou: 조직 단위(OU) 계층 구조 및 속성 조회
• windows_ad_update_ou: 조직 단위(OU) 속성 및 보호 설정 변경
• windows_ad_delete_ou: 조직 단위(OU) 삭제
• windows_ad_move_object: 사용자, 그룹, 컴퓨터, OU의 디렉토리 경로(OU) 이동
• windows_ad_list_groups: 보안/메일 그룹 목록 조회
• windows_ad_add_group_member: 특정 그룹에 사용자 추가
• windows_ad_remove_group_member: 특정 그룹에서 사용자 제거
• windows_ad_get_stale_objects: 일정 일수 이상 미접속(Stale)한 사용자/컴퓨터 조회
• windows_ad_disable_computer: 안 쓰는 컴퓨터 객체 비활성화

2. DNS 관리

• windows_dns_list_zones: DNS 서버 내 구성된 영역(Zone) 목록 조회
• windows_dns_get_records: 특정 영역 내의 DNS 레코드 조회
• windows_dns_add_record: A, CNAME 등 신규 레코드 등록
• windows_dns_update_record: 기존 DNS 레코드의 대상 값 수정 (A, CNAME)
• windows_dns_remove_record: 특정 DNS 레코드 영구 삭제

3. 그룹 정책 (GPO) 관리

• windows_gpo_list: 도메인 내의 그룹 정책 객체(GPO) 목록 조회
• windows_gpo_create: 신규 GPO 생성
• windows_gpo_delete: 기존 GPO 삭제
• windows_gpo_set_registry_value: GPO에 특정 레지스트리 정책 설정(추가/수정)
• windows_gpo_remove_registry_value: GPO에서 특정 레지스트리 정책 삭제

4. 이벤트 로그 (Event Log)

• windows_event_get_logs: System, Application, Security 등 중요 이벤트 로그 수집 및 필터링

5. 인프라 및 서비스 모니터링 (System)

• windows_system_metrics: CPU, Memory, C 드라이브 용량 등 성능 지표 조회
• windows_service_manage: Windows 핵심 서비스 상태 조회 및 Start/Stop/Restart 제어

6. 네트워크 관리 (DHCP)

• windows_dhcp_get_leases: 현재 활성 중인 IP 임대 정보 및 MAC 주소 조회
• windows_dhcp_add_reservation: MAC 주소 기반 정적 IP 예약 등록

🚀 초보자를 위한 설치 및 실행 가이드

이 MCP 서버는 Node.js 환경에서 동작합니다. 따라서 이 서버를 구동할 PC(AD 서버이든 외부 PC이든)에는 반드시 Node.js가 설치되어 있어야 합니다.

LLM(예: Claude Desktop, Cursor 등)이 Windows 서버를 제어하게 만드는 방법은 크게 상황에 따라 나뉩니다. 본인의 인프라 보안 환경에 맞춰 선택해 주세요.

💡 실무자를 위한 아키텍처 가이드: 어떤 방법을 선택해야 할까요?

• 방법 1 (로컬 방식): AD 서버 자체에 Claude Desktop과 같은 LLM 앱이 설치되어 있어야 합니다. 보통 운영 중인 AD 서버에는 외부 프로그램을 설치하지 않으므로, 이 방식은 개인 테스트 환경에만 적합합니다.
• 방법 2 & 방법 3 (원격 방식): 내 업무용 노트북(외부 PC)에만 LLM 클라이언트를 설치하고, AD 서버는 네트워크를 통해 원격으로 제어합니다. 실제 기업 및 실무 환경에서 가장 안전하고 강력하게 권장되는 방식입니다.

📖 방법 1. AD 서버에 직접 설치하여 실행하기 (로컬 실행 - 테스트용)

AD 서버(Domain Controller) 또는 도메인 관리용 PC(RSAT 설치)에 LLM 클라이언트를 직접 설치해서 사용하는 경우입니다.

1. Node.js 설치: AD 서버에 접속하여 Node.js를 다운로드하고 설치합니다.
2. LLM 클라이언트(Claude Desktop 등) 설치: AD 서버 안에 Claude Desktop 같은 프로그램을 직접 설치합니다.
3. 가장 중요한 관리자 권한 실행:
   • 바탕화면에 있는 Claude Desktop 아이콘을 우클릭한 뒤 반드시 **"관리자 권한으로 실행(Run as Administrator)"**을 클릭해서 켜야 합니다!
   • 이렇게 켜야지만 Claude가 AD 서버 시스템의 깊은 곳(계정 생성, 정책 변경 등)까지 건드릴 수 있는 권한을 얻게 됩니다.
4. MCP 클라이언트 설정: 관리자 권한으로 켜진 LLM 클라이언트의 mcpServers 설정 파일에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "windows-ad": {
      "command": "npx",
      "args": ["-y", "mcp-windows-ad"]
    }
  }
}

💡 설명: 바탕화면에서 관리자 권한으로 실행한 LLM 프로그램이, 그 권한을 그대로 물려받아 백그라운드에서 PowerShell 명령을 내리게 되는 원리입니다.

💻 방법 2. 외부 PC에서 원격으로 AD 제어하기 (SSH 원격 실행 - 실무 권장)

사용자의 노트북이나 외부 작업용 PC(Windows/Mac/Linux)에 LLM 클라이언트를 두고, 네트워크를 통해 원격으로 AD 서버(또는 관리 점프박스)에 SSH로 명령을 전송하는 방식입니다.

1. AD 서버(대상 서버) OpenSSH 설정:
   • 대상 Windows Server에 OpenSSH Server 기능이 설치되고 실행 중이어야 합니다. (TCP 22 포트 개방 필수)
2. 외부 PC(내 업무용 PC)에 Node.js 설치: 내 PC에 Node.js가 설치되어 있어야 합니다.
3. MCP 클라이언트 설정: 외부 PC의 LLM 설정 파일에 아래 내용을 추가합니다. 접속할 대상 서버의 IP와 SSH 인증 정보(Password 또는 Private Key)를 입력해야 합니다.

[옵션 A] 패스워드 인증 방식

{
  "mcpServers": {
    "windows-ad-remote": {
      "command": "npx",
      "args": ["-y", "mcp-windows-ad"],
      "env": {
        "AD_EXECUTION_MODE": "ssh",
        "AD_SSH_HOST": "192.168.1.100",
        "AD_SSH_PORT": "22",
        "AD_SSH_USER": "Administrator",
        "AD_SSH_PASSWORD": "secure_password123!"
      }
    }
  }
}

[옵션 B] 보안 키(Private Key) 인증 방식 (강력 권장)

{
  "mcpServers": {
    "windows-ad-remote": {
      "command": "npx",
      "args": ["-y", "mcp-windows-ad"],
      "env": {
        "AD_EXECUTION_MODE": "ssh",
        "AD_SSH_HOST": "192.168.1.100",
        "AD_SSH_PORT": "22",
        "AD_SSH_USER": "Administrator",
        "AD_SSH_PRIVATE_KEY_PATH": "C:/Users/myuser/.ssh/id_rsa"
      }
    }
  }
}

💡 설명: AD_EXECUTION_MODE를 ssh로 설정하면, 이 패키지는 내 업무용 PC에서 로컬 명령을 내리지 않고 입력된 대상 AD 서버로 SSH 명령을 전송하여 원격 실행합니다.

🌐 방법 3. HTTP / SSE 모드로 AD 서버에 상시 구동하기 (팀 단위 권장)

외부 PC 설정(방법 2) 외에도, AD 서버 자체에 백그라운드 웹 서버 형태로 MCP 서버 띄워두고 팀 내 여러 사용자가 접속하게 만들 수도 있습니다. 이 경우 AD 서버의 관리자 PowerShell에서 아래 명령어를 켜둡니다.

$env:TRANSPORT="http"
$env:PORT="3000"
npx -y mcp-windows-ad

이후 각 팀원들의 외부 LLM 클라이언트 설정에서는 위에서 띄운 서버 주소로 다음과 같이 접속할 수 있습니다. (이 방식 역시 AD 서버에 Claude를 설치할 필요가 없습니다)

{
  "mcpServers": {
    "windows-ad-sse": {
      "type": "sse",
      "url": "http://<AD서버_IP주소>:3000/mcp/sse"
    }
  }
}