de en es ja ko ru zh

Skills MCP AD

Name: Skills MCP AD
Author: DevSkillsIT

by DevSkillsIT

Overview Schema Source Related Servers Discussions Admin

Python

Remote

소개

Active Directory MCP는 AI 어시스턴트(Claude, Gemini CLI, API를 통한 ChatGPT 등)가 Active Directory 환경을 안전하게 관리할 수 있게 해주는 오픈소스 Model Context Protocol 서버입니다.

주요 기능

47개 도구: 사용자, 그룹, 컴퓨터, OU, 보안, 감사, 그리고 15개의 MSP 프롬프트 플레이북을 다룹니다.
세 가지 전송 방식: stdio(server.py), FastMCP 기반 Streamable HTTP(server_http.py), FastAPI 기반 Streamable HTTP(server_fastapi.py).
설계상 멀티테넌트: 각 인스턴스는 AD_MCP_CONFIG를 통해 자체 AD에 바인딩됩니다. 동일한 코드베이스로 한 호스트에서 무제한 테넌트를 서비스할 수 있습니다.
쓰기 작업 보호 장치: 모든 변경 도구는 AD에 접근하기 전에 테넌트별 클라이언트 확인 문자열 또는 자동화 Bearer 토큰을 요구합니다.
모든 작업에 대한 감사 로그: 각 호출은 작업 이름, 대상, 모드(CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED) 및 결과를 기록합니다.

명명 규칙

모든 MCP 도구 이름은 ad_* 접두사와 설명적인 접미사를 사용합니다 — 예: ad_list_users_with_filters, ad_create_user_account, ad_disable_computer_account_trust. 이는 이 MCP가 동일한 AI 클라이언트에 연결된 다른 서버(GLPI, Hudu 등)와 함께 실행될 때 충돌을 방지합니다.

Related MCP server: Shell MCP

멀티테넌트 아키텍처

이 MCP는 테넌트당 하나의 프로세스로 실행되도록 설계되었으며, 모두 동일한 코드를 공유합니다:

.base-code/                    <- this repository (shared source of truth)
  src/active_directory_mcp/
  ad-config/
    ad-config.example.json     <- template only (real configs are .gitignored)

<deployment>/                  <- one directory per tenant, OUTSIDE this repo
  tenant-a/
    ad-config/ad-config.json   <- real credentials (NEVER committed)
    start.sh                   <- exports AD_MCP_CONFIG and launches the server
  tenant-b/
    ad-config/ad-config.json
    start.sh

각 start.sh는 해당 테넌트의 구성을 가리키는 AD_MCP_CONFIG를 내보내고 전용 포트에서 python -m active_directory_mcp.server_http를 실행합니다. 공유 .base-code/를 한 번 업데이트하고 모든 테넌트를 재시작하면 됩니다 — 동일한 코드, 격리된 상태.

빠른 시작

사전 요구 사항

Python 3.11+
호스트에서 LDAP/LDAPS에 연결 가능
노출하려는 작업에 필요한 권한을 가진 AD 서비스 계정

1. 설치

git clone https://github.com/DevSkillsIT/Skills-MCP-Active-Directory.git
cd Skills-MCP-Active-Directory

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows

pip install -e .                   # installs from pyproject.toml

2. 구성

mkdir -p /etc/ad-mcp
cp ad-config/ad-config.example.json /etc/ad-mcp/ad-config.json
$EDITOR /etc/ad-mcp/ad-config.json   # set server, bind_dn, password, base_dn, OUs
chmod 600 /etc/ad-mcp/ad-config.json

예제 파일은 git에 유지되는 유일한 템플릿입니다. 실제 ad-config.json은 .gitignore(ad-config/*.json + !ad-config/*.example.json)에 의해 차단됩니다.

3. 실행

export AD_MCP_CONFIG=/etc/ad-mcp/ad-config.json

# stdio transport (for direct Claude Desktop / mcp-cli use):
python -m active_directory_mcp.server

# HTTP transport (for Claude Code, Gemini CLI, n8n, etc.):
python -m active_directory_mcp.server_http --host 0.0.0.0 --port 8813 --path /activedirectory-mcp

4. Claude Code에서 연결

claude mcp add --transport http ad http://localhost:8813/activedirectory-mcp \
  --headers "Authorization: Bearer YOUR_AUTOMATION_TOKEN"

5. Gemini CLI에서 연결

~/.gemini/settings.json:

{
  "mcpServers": {
    "ad": {
      "httpUrl": "http://localhost:8813/activedirectory-mcp",
      "headers": { "Authorization": "Bearer YOUR_AUTOMATION_TOKEN" },
      "timeout": 30000
    }
  }
}

도구

모든 도구는 ad_* 접두사를 사용합니다. 쓰기로 표시된 도구는 확인 문자열 또는 자동화 Bearer 토큰이 필요합니다.

테넌트 식별 (3)

도구	작업
`ad_get_client_tenant_info`	이 인스턴스의 테넌트 정보 반환 (먼저 호출)
`ad_list_configured_clients`	클라이언트 레지스트리에 등록된 모든 클라이언트 나열
`ad_check_client_configuration`	주어진 클라이언트 slug에 AD가 구성되어 있는지 확인

사용자 관리 (9)

도구	쓰기	작업
`ad_list_users_with_filters`	—	사용자 나열 (선택적으로 OU/기준으로 필터링)
`ad_get_user_details_by_username`	—	sAMAccountName으로 사용자 속성 가져오기
`ad_get_user_group_memberships`	—	사용자가 속한 그룹 나열
`ad_create_user_account`	예	새 사용자 생성
`ad_modify_user_attributes`	예	사용자 속성 수정
`ad_delete_user_account_permanently`	예	사용자 삭제
`ad_enable_user_account_access`	예	사용자 계정 활성화
`ad_disable_user_account_access`	예	사용자 계정 비활성화
`ad_reset_user_password_forced`	예	비밀번호 재설정 (다음 로그인 시 강제 변경)

그룹 관리 (8)

도구	쓰기	작업
`ad_list_groups_with_filters`	—	그룹 나열
`ad_get_group_details_by_name`	—	그룹 속성 가져오기
`ad_get_group_members_recursive`	—	구성원 나열, 선택적으로 재귀
`ad_create_group_security_or_distribution`	예	보안 또는 메일 그룹 생성
`ad_modify_group_attributes`	예	그룹 속성 수정
`ad_delete_group_permanently`	예	그룹 삭제
`ad_add_member_to_group`	예	구성원 추가
`ad_remove_member_from_group`	예	구성원 제거

컴퓨터 관리 (8)

도구	쓰기	작업
`ad_list_computers_with_filters`	—	컴퓨터 나열
`ad_get_computer_details_by_name`	—	컴퓨터 속성 가져오기
`ad_get_inactive_computers_by_days`	—	N일 이상 유휴 상태인 컴퓨터 나열
`ad_create_computer_account`	예	컴퓨터 개체 생성
`ad_modify_computer_attributes`	예	컴퓨터 속성 수정
`ad_delete_computer_account_permanently`	예	컴퓨터 개체 삭제
`ad_enable_computer_account_trust`	예	컴퓨터 계정 활성화
`ad_disable_computer_account_trust`	예	컴퓨터 계정 비활성화
`ad_reset_computer_password_trust`	예	컴퓨터 보안 채널 비밀번호 재설정

OU(조직 구성 단위) 관리 (7)

도구	쓰기	작업
`ad_list_organizational_units_hierarchy`	—	OU 나열 (재귀 옵션)
`ad_get_organizational_unit_details`	—	OU 속성 가져오기
`ad_get_organizational_unit_objects`	—	OU 내부의 개체 나열
`ad_create_organizational_unit`	예	OU 생성
`ad_modify_organizational_unit_attributes`	예	OU 수정
`ad_delete_organizational_unit_forced`	예	OU 삭제 (비어 있지 않은 OU 삭제는 force=true)
`ad_move_organizational_unit_parent`	예	OU를 새 부모로 이동

보안 및 감사 (6)

도구	작업
`ad_get_domain_security_policy_info`	도메인 정보 + 비밀번호/잠금 정책
`ad_get_privileged_security_groups`	권한 있는 그룹 나열 (Domain Admins, Enterprise Admins 등)
`ad_get_user_effective_permissions`	사용자의 유효 권한 표시
`ad_get_inactive_users_by_days`	N일 이상 로그온하지 않은 사용자
`ad_get_password_policy_violations`	비밀번호 정책을 위반하는 계정
`ad_audit_administrative_accounts`	권한 있는 계정 위생 감사

MSP 프롬프트 (도구 2개 + 프롬프트 15개)

도구	작업
`ad_list_msp_prompts`	15개의 전문 MSP 플레이북 나열 (관리자 및 분석가)
`ad_execute_msp_prompt`	인자와 함께 지정된 플레이북 실행

전체 프롬프트 카탈로그(보안 감사, 온보딩, 오프보딩, 비밀번호 재설정 플레이북 등)는 PROMPTS.md를 참조하세요.

시스템 (4)

도구	작업
`ad_test_ldap_connection_status`	LDAP 연결 프로브
`ad_health_check_mcp_server`	전체 상태 점검 (서버 + LDAP 검색 테스트 + 통계)
`ad_get_mcp_schema_tools_info`	등록된 모든 도구의 자체 설명 스키마

구성

런타임 구성 파일 경로는 AD_MCP_CONFIG 환경 변수를 통해 제공됩니다. 스키마는 ad-config/ad-config.example.json에 있습니다.

주요 필드

필드	필수	설명
`active_directory.server`	예	기본 LDAP URL, 예: `ldaps://dc.example.com:636`
`active_directory.server_pool`	아니요	장애 조치(failover)용 추가 LDAP URL
`active_directory.bind_dn`	예	서비스 계정의 전체 DN
`active_directory.password`	예	서비스 계정 비밀번호 (`chmod 600`으로 파일 권한 유지)
`active_directory.base_dn`	예	기본 DN, 예: `DC=example,DC=com`
`organizational_units.*`	예	사용자/그룹/컴퓨터/서비스 계정의 기본 OU
`security.enable_tls`	아니요	StartTLS / LDAPS 강제 적용
`security.validate_certificate`	아니요	`ca_cert_file`에 대해 서버 인증서 검증
`security.require_secure_connection`	아니요	평문(plaintext) 바인딩 거부
`automation.token`	아니요	무인 쓰기 작업용 Bearer 토큰
`client.slug`	아니요	`ad_get_client_tenant_info`가 보고하는 테넌트 식별자

서비스 계정 권한

바인딩 계정에 노출하려는 작업에 필요한 최소 위임 권한을 부여하세요:

읽기 전용 배포: 도메인 루트에 "모든 속성 읽기" + "내용 나열"이면 충분합니다.
사용자/그룹 쓰기: 대상 OU에 "개체 만들기/삭제" + "모든 속성 쓰기"를 위임하세요.
비밀번호 재설정: 대상 OU에 "비밀번호 재설정" 확장 권한을 위임하세요.
컴퓨터 가입/탈퇴: 컴퓨터 OU에 "컴퓨터 개체 만들기/삭제"를 위임하세요.

항상 전용 서비스 계정을 사용하고, 프로덕션에서는 LDAPS를 사용하며, 비밀번호를 정기적으로 교체하세요.

보안

쓰기 보호 모델

모든 변경 도구(ad_create_*, ad_modify_*, ad_delete_*, ad_enable_*, ad_disable_*, ad_reset_*, ad_add_*, ad_remove_*, ad_move_*)는 LDAP에 도달하기 전에 check_write_permission()을 호출합니다. 다음 중 하나에 해당하면 쓰기를 허용합니다:

automation_token이 구성의 automation.token과 일치 — CI / 예약 작업용.
client_confirmation이 테넌트 슬러그와 일치 — AI 어시스턴트가 먼저 ad_get_client_tenant_info를 호출하고, 슬러그를 사용자에게 읽어 준 다음, 해당 정확한 문자열을 전달해야 합니다.
테넌트에 require_confirmation_for_writes: false가 설정된 경우 (명시적 옵트아웃, 권장되지 않음).

위 중 어느 것도 충족되지 않으면 호출은 permitted: false 메시지로 단락(short-circuit)되고 LDAP 쓰기는 시도되지 않습니다.

감사 로깅

모든 작업은 타임스탬프, 도구 이름, 대상, 확인 모드(AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED), 성공/실패를 포함한 구조화된 로그 줄을 기록합니다. 로그는 logging.file이 가리키는 위치에 저장됩니다.

비밀 정보 관리

실제 ad-config.json 파일은 git-ignore 처리됩니다. *.example.json만 추적됩니다.
실제 password 또는 automation.token이 포함된 구성을 제3자가 기록하거나 전사하는 채팅에 붙여넣지 마세요.
automation.token을 재생성할 때마다 교체하세요. 권한 있는 자격 증명으로 취급하세요.

테스트

# Unit + integration tests
pytest tests/ -v

# Coverage
pytest --cov=src --cov-report=term-missing

# Lint
ruff check .

번들로 제공되는 docker-compose-ad.yml은 192.168.1.100에 Samba AD 컨테이너와 MCP 컨테이너를 띄워 통합 테스트가 프로덕션에 영향을 주지 않고 실제 LDAP 백엔드에 대해 실행될 수 있게 합니다.

문제 해결

증상	가능한 원인	해결 방법
`LDAP bind failed`	잘못된 `bind_dn` / `password`	`ldapsearch -H <server> -D '<bind_dn>' -W`로 확인
`Insufficient permissions`	서비스 계정에 위임 권한 없음	대상 OU에 다시 위임
`Certificate verification failed`	신뢰되지 않은 자체 서명 인증서	`ca_cert_file` 설정 또는 `validate_certificate: false` (테스트 전용)
모든 쓰기에서 `permitted: false`	확인/토큰 누락	먼저 `ad_get_client_tenant_info` 호출 또는 `automation_token` 전달
`Health degraded`	소켓은 열렸지만 LDAP 검색 실패	서비스 계정 잠금 / 복제 / 네트워크 ACL 확인

기여

저장소를 포크하세요.
기능 브랜치를 만드세요: git checkout -b feat/your-feature.
테스트를 실행하세요: pytest.
명확한 설명과 관련 이슈 링크와 함께 PR을 여세요.

커밋은 Conventional Commits을 따릅니다.

라이선스

MIT — LICENSE 참조.

감사의 글

Alperen Adalar의 업스트림 alpadalar/ActiveDirectoryMCP 프로젝트 기반.
mcp, fastmcp, ldap3 및 FastAPI 위에 구축됨.

지원

버그 신고: GitHub Issues
토론: GitHub Discussions

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

Server4Agent A
com.server4agent
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
App Automation Cloud Platforms Developer Tools
343
https://mcp.server4agent.com
Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
https://api.artificialwit.com/mcp
Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
Zapier
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
https://mcp.zapier.com/api/v1/connect

Related MCP Servers

ActiveDirectoryMCP
Security Databases
alpadalar
A
license
B
quality
B
maintenance
A comprehensive MCP server for managing Active Directory environments through LDAP, enabling user, group, computer, and OU management, as well as security auditing and policy compliance checks.
Updated a day ago (2026-11-04 07:27 UTC)
45
52
MIT
Shell MCP
Shell Access Command Line
luciVuc
A
license
A
quality
D
maintenance
A production-ready MCP server that enables AI assistants to execute shell commands, manage files, monitor system resources, and automate complex workflows with advanced features like stock tracking and web automation.
Updated 7 months ago (2026-04-09 19:59 UTC)
7
17 npm
MIT
LegacyMCP
Security Monitoring
Marco-Lelli
A
license
Not graded
quality
C
maintenance
MCP server that enables AI-powered assessment of Active Directory on-premises environments by exposing AD data as queryable tools for LLMs like Claude.
Updated 3 months ago (2026-08-14 05:47 UTC)
MIT
windows-admin-mcp
OS Automation Shell Access Observability
devladpopov
A
license
Not graded
quality
D
maintenance
An MCP server that enables AI assistants to manage, monitor, and diagnose Windows systems through 42 tools across 8 modules, including services, event viewer, task scheduler, processes, network, diagnostics, observability, and safety features.
Updated 6 months ago (2026-05-18 11:33 UTC)
18 npm
9
MIT

소개