Skills MCP AD

О проекте

Active Directory MCP — это сервер с открытым исходным кодом, реализующий Model Context Protocol, который позволяет ИИ-ассистентам (Claude, Gemini CLI, ChatGPT через API и др.) безопасно управлять средами Active Directory.

Ключевые возможности

• 47 инструментов, покрывающих пользователей, группы, компьютеры, OU, безопасность, аудит и 15 плейбуков для MSP-провайдеров.

• Три транспорта: stdio (server.py), Streamable HTTP через FastMCP (server_http.py) и Streamable HTTP через FastAPI (server_fastapi.py).

• Мультитенантность из коробки: каждый экземпляр привязан к своему AD через AD_MCP_CONFIG; одна и та же кодовая база может обслуживать неограниченное число тенантов с одного хоста.

• Защита операций записи: каждый изменяющий инструмент требует либо строку подтверждения клиента для конкретного тенанта, либо Bearer-токен автоматизации перед обращением к AD.

• Журнал аудита для каждой операции: каждый вызов фиксирует имя операции, цель, режим (CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED) и результат.

Соглашение об именовании

Все имена инструментов MCP используют префикс ad_* с описательным суффиксом — например, ad_list_users_with_filters, ad_create_user_account, ad_disable_computer_account_trust. Это позволяет избежать конфликтов имён, когда этот MCP работает вместе с другими серверами (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_*. Инструменты, помеченные как Write, требуют строку подтверждения ИЛИ Bearer-токен автоматизации.

Идентификация тенанта (3)

Управление пользователями (9)

Управление группами (8)

Управление компьютерами (8)

Управление подразделениями (7)

Безопасность и аудит (6)

Промпты для MSP (2 инструмента + 15 промптов)

Полный каталог промптов см. в PROMPTS.md (аудит безопасности, онбординг, офбординг, плейбук сброса пароля и т. д.).

Системные (4)

Конфигурация

Путь к файлу конфигурации времени выполнения задаётся через переменную окружения AD_MCP_CONFIG. Схема — в ad-config/ad-config.example.json.

Ключевые поля

Разрешения сервисной учетной записи

Предоставьте учетной записи привязки минимальные делегированные права, необходимые для операций, которые вы планируете открыть:

• Развертывания только для чтения: достаточно «Чтение всех свойств» + «Список содержимого» в корне домена.

• Запись пользователей/групп: делегируйте «Создание/удаление объектов» + «Запись всех свойств» в целевых подразделениях.

• Сброс пароля: делегируйте расширенное право «Сброс пароля» в целевых подразделениях.

• Ввод/вывод компьютеров: делегируйте «Создание/удаление объектов компьютеров» в подразделении компьютеров.

Всегда используйте выделенную сервисную учетную запись, LDAPS в производственной среде и регулярно меняйте пароль.

Безопасность

Модель защиты записи

Каждый изменяющий инструмент (ad_create_*, ad_modify_*, ad_delete_*, ad_enable_*, ad_disable_*, ad_reset_*, ad_add_*, ad_remove_*, ad_move_*) вызывает check_write_permission() перед обращением к LDAP. Он разрешает запись, если выполняется одно из условий:

1. automation_token совпадает с automation.token в конфигурации — предназначен для CI / запланированных заданий.

2. client_confirmation совпадает с идентификатором тенанта — ИИ-ассистент должен сначала вызвать ad_get_client_tenant_info, прочитать идентификатор пользователю и передать эту точную строку.

3. У тенанта установлено require_confirmation_for_writes: false (явный отказ, не рекомендуется).

Если ни одно из вышеперечисленных условий не выполнено, вызов завершается сообщением permitted: false, и запись в LDAP не выполняется.

Журналирование аудита

Все операции записывают структурированную строку журнала, включающую: временную метку, имя инструмента, цель, режим подтверждения (AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED) и успех/неудачу. Журналы сохраняются туда, куда указывает logging.file.

Гигиена секретов

• Реальные файлы ad-config.json игнорируются git. Отслеживаются только *.example.json.

• Никогда не вставляйте конфигурацию с реальным password или automation.token в чат, который логируется или транскрибируется третьей стороной.

• Меняйте automation.token при каждой его регенерации; относитесь к нему как к привилегированному удостоверению.

Тестирование

# Unit + integration tests
pytest tests/ -v

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

# Lint
ruff check .

Встроенный docker-compose-ad.yml поднимает контейнер Samba AD на 192.168.1.100 и контейнер MCP, чтобы интеграционные тесты могли выполняться с реальным LDAP-бэкендом, не затрагивая производственную среду.

Устранение неполадок

Вклад в проект

1. Сделайте форк репозитория.

2. Создайте ветку функции: git checkout -b feat/your-feature.

3. Запустите тесты: pytest.

4. Откройте PR с понятным описанием и ссылкой на соответствующий issue.

Коммиты следуют Conventional Commits.

Лицензия

MIT — см. LICENSE.

Благодарности

• Основано на вышестоящем проекте alpadalar/ActiveDirectoryMCP от Alperen Adalar.

• Построено на основе mcp, fastmcp, ldap3 и FastAPI.

Поддержка

• Сообщения об ошибках: GitHub Issues

• Обсуждения: GitHub Discussions