Skills MCP AD

Überblick

Active Directory MCP ist ein Open-Source-Model Context Protocol-Server, der es KI-Assistenten (Claude, Gemini CLI, ChatGPT über API usw.) ermöglicht, Active-Directory-Umgebungen sicher zu verwalten.

Hauptfunktionen

• 47 Tools für Benutzer, Gruppen, Computer, OUs, Sicherheit, Audit und 15 MSP-Prompt-Playbooks.

• Drei Transports: stdio (server.py), Streamable HTTP über FastMCP (server_http.py) und Streamable HTTP über FastAPI (server_fastapi.py).

• Von Natur aus Multi-Tenant-fähig: Jede Instanz bindet sich über AD_MCP_CONFIG an ihr eigenes AD; dieselbe Codebasis kann unbegrenzt viele Mandanten von einem Host aus bedienen.

• Schutzmechanismen für Schreiboperationen: Jedes ändernde Tool erfordert entweder eine mandantenspezifische Client-Bestätigungszeichenfolge oder ein Automatisierungs-Bearer-Token, bevor es AD verändert.

• Audit-Protokoll für jeden Vorgang: Jeder Aufruf protokolliert Operationsname, Ziel, Modus (CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED) und Ergebnis.

Namenskonvention

Alle MCP-Toolnamen verwenden das Präfix ad_* mit einem beschreibenden Suffix — z. B. ad_list_users_with_filters, ad_create_user_account, ad_disable_computer_account_trust. Dies vermeidet Kollisionen, wenn dieses MCP neben anderen Servern (GLPI, Hudu usw.) läuft, die mit demselben KI-Client verbunden sind.

Related MCP server: Shell MCP

Multi-Tenant-Architektur

Dieses MCP ist dafür ausgelegt, als ein Prozess pro Mandant zu laufen, wobei alle dieselbe Codebasis verwenden:

.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

Jedes start.sh exportiert AD_MCP_CONFIG, das auf die Konfiguration des jeweiligen Mandanten verweist, und führt python -m active_directory_mcp.server_http auf einem dedizierten Port aus. Aktualisieren Sie das gemeinsame .base-code/ einmal, starten Sie alle Mandanten neu — gleicher Code, isolierter Zustand.

Schnellstart

Voraussetzungen

• Python 3.11+

• LDAP/LDAPS vom Host aus erreichbar

• Ein AD-Dienstkonto mit den Berechtigungen, die für die Operationen erforderlich sind, die Sie freigeben möchten

1. Installation

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. Konfiguration

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

Die Beispieldatei ist die einzige Vorlage, die in Git gepflegt wird. Jede echte ad-config.json wird durch .gitignore blockiert (ad-config/*.json + !ad-config/*.example.json).

3. Ausführen

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. Verbindung mit Claude Code

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

5. Verbindung mit Gemini CLI

~/.gemini/settings.json:

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

Tools

Alle Tools verwenden das Präfix ad_*. Als Write markierte Tools erfordern eine Bestätigungszeichenfolge ODER ein Automatisierungs-Bearer-Token.

Mandantenidentifikation (3)

Benutzerverwaltung (9)

Gruppenverwaltung (8)

Computerverwaltung (8)

Verwaltung von Organisationseinheiten (7)

Sicherheit & Audit (6)

MSP-Prompts (2 Tools + 15 Prompts)

Die vollständige Prompt-Übersicht finden Sie in PROMPTS.md (Sicherheitsaudit, Onboarding, Offboarding, Passwort-Reset-Playbook usw.).

System (4)

Konfiguration

Der Pfad zur Laufzeitkonfigurationsdatei wird über die Umgebungsvariable AD_MCP_CONFIG bereitgestellt. Schema in ad-config/ad-config.example.json.

Wichtige Felder

Berechtigungen für Dienstkonten

Gewähren Sie dem Bind-Konto die minimalen delegierten Rechte, die für die von Ihnen beabsichtigten Operationen erforderlich sind:

• Nur-Lese-Bereitstellungen: „Alle Eigenschaften lesen" + „Inhalte auflisten" auf der Domänenwurzel reicht aus.

• Benutzer/Gruppen-Schreiben: Delegieren Sie „Objekte erstellen/löschen" + „Alle Eigenschaften schreiben" auf den Ziel-OUs.

• Passwort zurücksetzen: Delegieren Sie das erweiterte Recht „Passwort zurücksetzen" auf den Ziel-OUs.

• Computer beitreten/verlassen: Delegieren Sie „Computerobjekte erstellen/löschen" auf der Computer-OU.

Verwenden Sie immer ein dediziertes Dienstkonto, LDAPS in der Produktion und rotieren Sie das Passwort regelmäßig.

Sicherheit

Schreibschutzmodell

Jedes mutierende Tool (ad_create_*, ad_modify_*, ad_delete_*, ad_enable_*, ad_disable_*, ad_reset_*, ad_add_*, ad_remove_*, ad_move_*) ruft check_write_permission() auf, bevor es LDAP erreicht. Es akzeptiert den Schreibvorgang, wenn eines der folgenden zutrifft:

1. automation_token stimmt mit automation.token in der Konfiguration überein – für CI / geplante Jobs vorgesehen.

2. client_confirmation stimmt mit dem Mandanten-Slug überein – der KI-Assistent muss zuerst ad_get_client_tenant_info aufrufen, den Slug dem Benutzer vorlesen und genau diese Zeichenfolge übergeben.

3. Der Mandant hat require_confirmation_for_writes: false (expliziter Opt-out, nicht empfohlen).

Wenn keine der oben genannten Bedingungen erfüllt ist, wird der Aufruf mit einer permitted: false-Meldung abgebrochen und der LDAP-Schreibvorgang wird nie versucht.

Audit-Protokollierung

Alle Operationen schreiben eine strukturierte Protokollzeile mit: Zeitstempel, Tool-Name, Ziel, Bestätigungsmodus (AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED) und Erfolg/Fehler. Die Protokolle gehen dorthin, wo logging.file zeigt.

Geheimnis-Hygiene

• Echte ad-config.json-Dateien sind git-ignoriert. Nur *.example.json wird verfolgt.

• Fügen Sie niemals eine Konfiguration mit einem echten password oder automation.token in einen Chat ein, der von Dritten protokolliert oder transkribiert wird.

• Rotieren Sie automation.token bei jeder Neugenerierung; behandeln Sie es als privilegierte Anmeldeinformation.

Testen

# Unit + integration tests
pytest tests/ -v

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

# Lint
ruff check .

Ein gebündeltes docker-compose-ad.yml startet einen Samba-AD-Container unter 192.168.1.100 sowie einen MCP-Container, sodass die Integrationstests gegen ein echtes LDAP-Backend laufen können, ohne die Produktion zu berühren.

Fehlerbehebung

Mitwirken

1. Forken Sie das Repository.

2. Erstellen Sie einen Feature-Branch: git checkout -b feat/your-feature.

3. Führen Sie Tests aus: pytest.

4. Öffnen Sie einen PR mit einer klaren Beschreibung und einem Link zum relevanten Issue.

Commits folgen Conventional Commits.

Lizenz

MIT – siehe LICENSE.

Danksagungen

• Basierend auf dem Upstream-Projekt alpadalar/ActiveDirectoryMCP von Alperen Adalar.

• Aufgebaut auf mcp, fastmcp, ldap3 und FastAPI.

Support

• Fehlerberichte: GitHub Issues

• Diskussionen: GitHub Discussions