Skip to main content
Glama
deenesjakoruzh
DevSkillsIT

Skills MCP AD

by DevSkillsIT
OverviewSchemaRelated ServersScoreDiscussions
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()을 호출합니다. 다음 중 하나에 해당하면 쓰기를 허용합니다:

  1. automation_token이 구성의 automation.token과 일치 — CI / 예약 작업용.

  2. client_confirmation이 테넌트 슬러그와 일치 — AI 어시스턴트가 먼저 ad_get_client_tenant_info를 호출하고, 슬러그를 사용자에게 읽어 준 다음, 해당 정확한 문자열을 전달해야 합니다.

  3. 테넌트에 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 확인

기여

  1. 저장소를 포크하세요.

  2. 기능 브랜치를 만드세요: git checkout -b feat/your-feature.

  3. 테스트를 실행하세요: pytest.

  4. 명확한 설명과 관련 이슈 링크와 함께 PR을 여세요.

커밋은 Conventional Commits을 따릅니다.

라이선스

MIT — LICENSE 참조.

감사의 글

지원

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • PMCP - Perfect Model Context

    NoobyNull
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A comprehensive production-ready MCP server with AI integration, plugin management, and web-based administration. Features multi-database support, RAG capabilities, SSH/SFTP access, and a built-in plugin hub for managing the MCP ecosystem.

  • Shell MCP

    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.
    7
    32
    MIT

  • LegacyMCP

    Marco-Lelli
    A
    license
    Not graded
    quality
    A
    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.
    MIT

  • windows-admin-mcp

    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.
    32
    8
    MIT

View all related MCP servers

Related MCP Connectors

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

  • gainium-mcp

    MCP server for Gainium — manage trading bots, deals, and balances via AI assistants

  • royal-mcp

    Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DevSkillsIT/Skills-MCP-Active-Directory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server