Skip to main content
Glama
MCP Active Directory Server

MCP Active Directory Server

by AlexLiAtDuo

MCP Active Directory Server

npm version License Node.js Platform

The first Model Context Protocol (MCP) server for Windows Active Directory - enabling AI agents like Claude to query, diagnose, and interact with Domain Controllers.

Overview

Active Directory is the backbone of enterprise identity management, yet there has been no way for AI agents to interact with it directly. This MCP server bridges that gap, allowing AI assistants to:

  • Query AD objects via LDAP with custom filters and attributes

  • Test authentication using Kerberos and LDAP bind operations

  • Monitor security events including logon attempts, ticket requests, and authentication failures

  • Diagnose infrastructure by checking WinRM configuration and DC health

  • Discover service accounts including Group Managed Service Accounts (gMSAs)

No equivalent exists from Microsoft. While Microsoft provides AD PowerShell cmdlets, there is no MCP server enabling AI agent integration with Active Directory.

Why This Matters

Enterprise IT teams spend significant time troubleshooting AD authentication issues, auditing service accounts, and investigating security events. With this MCP server, AI agents can:

  • Instantly diagnose "why can't user X authenticate?" by testing Kerberos and LDAP

  • Audit service accounts across the domain in seconds

  • Correlate security events to identify suspicious patterns

  • Answer AD questions without requiring deep PowerShell expertise

Related MCP server: PentestMCP

Features

Tool

Description

ad_get_dc_info

Get Domain Controller hostname, OS version, uptime, and list of all DCs in the domain

ad_ldap_query

Run LDAP queries with custom filters, search bases, and attribute selection

ad_test_kerberos_auth

Test Kerberos authentication by requesting a TGT for a specified user

ad_test_ldap_bind

Test LDAP/LDAPS simple bind authentication for a user

ad_get_user_groups

Get all groups (including nested) that a user is a member of

ad_list_service_accounts

List Group Managed Service Accounts (gMSAs) and service accounts

ad_get_security_events

Query Windows Security events (4624, 4625, 4768, 4769, 4776)

ad_diagnose_winrm

Diagnose WinRM HTTPS configuration on a Domain Controller

ad_run_command

Execute arbitrary PowerShell commands (disabled by default, requires explicit opt-in)

Installation

Prerequisites

  • Node.js 18+ - Download

  • Windows OS - Required for PowerShell remoting via WinRM

  • Network access to Domain Controller(s) on port 5986 (WinRM HTTPS)

  • AD credentials with appropriate permissions (Domain Admin or delegated)

Install from npm

npm install -g mcp-active-directory-server

Install from Source

git clone https://github.com/cisco-sbg/mcp-active-directory-server.git
cd mcp-active-directory-server
npm install
npm run build

Configuration

The server supports multiple credential sources, checked in order:

  1. Environment variables (recommended for development)

  2. MACHINES.TXT file (for multi-DC environments)

  3. Windows Credential Manager (most secure for production)

Environment Variables

# Required
AD_DC=dc01.corp.local          # Domain Controller hostname or IP
AD_USERNAME=admin@corp.local   # AD username (UPN or DOMAIN\user format)
AD_PASSWORD=your-password      # AD password

# Optional
AD_DOMAIN=corp.local           # Domain name (auto-detected if omitted)
AD_SKIP_CERT_VALIDATION=true   # Skip TLS cert validation (self-signed certs only)
AD_ENABLE_RUN_COMMAND=true     # Enable ad_run_command tool (disabled by default)

Multi-DC Configuration

For environments with multiple Domain Controllers, use target-specific suffixes:

# Primary DC
AD_DC_DC1=dc01.corp.local
AD_USERNAME_DC1=admin@corp.local
AD_PASSWORD_DC1=password1

# Secondary DC
AD_DC_DC2=dc02.corp.local
AD_USERNAME_DC2=admin@corp.local
AD_PASSWORD_DC2=password2

Then specify the target in tool calls: ad_get_dc_info --target DC1

Domain Controller Setup

WinRM HTTPS must be configured on target DCs. A setup script is included:

# Run on each Domain Controller (as Administrator)
.\scripts\setup-dc-winrm.ps1

This script:

  • Enables WinRM HTTPS listener on port 5986

  • Creates a self-signed certificate (or uses existing CA cert)

  • Configures firewall rules

Usage with Claude Code

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "ad-tools": {
      "command": "npx",
      "args": ["mcp-active-directory-server"],
      "env": {
        "AD_DC": "dc01.corp.local",
        "AD_USERNAME": "admin@corp.local",
        "AD_PASSWORD": "your-password"
      }
    }
  }
}

For self-signed certificates (lab environments):

{
  "mcpServers": {
    "ad-tools": {
      "command": "npx",
      "args": ["mcp-active-directory-server"],
      "env": {
        "AD_DC": "dc01.corp.local",
        "AD_USERNAME": "admin@corp.local",
        "AD_PASSWORD": "your-password",
        "AD_SKIP_CERT_VALIDATION": "true"
      }
    }
  }
}

Use Cases

Troubleshoot Authentication Failures

"Why can't user jsmith authenticate?"

The AI agent can:

  1. Test Kerberos TGT request with ad_test_kerberos_auth

  2. Test LDAP bind with ad_test_ldap_bind

  3. Check recent security events with ad_get_security_events

  4. Report specific failure reason (locked account, expired password, etc.)

Audit Service Accounts

"List all service accounts and their last password change"

ad_list_service_accounts

Returns gMSAs and accounts matching svc*, service* patterns with password age, enabling compliance audits.

Investigate Security Events

"Show me failed login attempts from the last hour"

ad_get_security_events --eventIds 4625 --minutes 60

Returns Event ID 4625 (failed logon) events with source IP, username, and failure reason.

Query AD Objects

"Find all users in the Engineering OU who haven't logged in for 90 days"

ad_ldap_query --filter "(objectClass=user)" --searchBase "OU=Engineering,DC=corp,DC=local" --attributes "sAMAccountName,lastLogonTimestamp"

Diagnose Infrastructure

"Is WinRM properly configured on the domain controllers?"

ad_diagnose_winrm

Returns listener configuration, certificate details, and connectivity status.

Security

This server executes PowerShell commands on Domain Controllers. Please review SECURITY.md before deployment.

Key Security Features

Feature

Description

Credential Protection

Passwords passed via stdin, never in process command lines

LDAP Injection Prevention

RFC 4515 escaping for all filter values

PowerShell Injection Prevention

Proper escaping for string interpolation

Audit Logging

All operations logged to logs/audit-YYYY-MM-DD.jsonl

WinRM HTTPS Only

Connections use port 5986 with TLS encryption

Dangerous Tool Disabled

ad_run_command requires explicit AD_ENABLE_RUN_COMMAND=true

Reporting Security Issues

Report vulnerabilities via:

Known Issues

  • LDAPS bind testing may fail with certain certificate configurations. Use Kerberos authentication testing as an alternative.

  • WinRM HTTP (port 5985) is not supported. Always use HTTPS on port 5986.

Getting Help

Getting Involved

Contributions are welcome! See CONTRIBUTING.md for:

  • Development setup

  • Code style guidelines

  • Pull request process

Credits

  • Author: Cisco Systems, Inc.

  • MCP SDK: Anthropic

License

Apache 2.0 - Copyright 2024 Cisco Systems, Inc.


Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries.

Available Tools

9 tools
ad_diagnose_winrmA

Diagnose WinRM configuration on target (listeners, firewall rules, network profile, service status). Use to troubleshoot connectivity issues.

Inputs: target.

ad_get_dc_infoB

Get basic info about the Domain Controller (hostname, OS, uptime, services)

Inputs: target.

ad_get_security_eventsB

Get recent Windows Security events related to authentication (4624, 4625, 4768, 4769, 4776)

Inputs: target, minutes, eventIds, username.

ad_get_user_groupsA

Get all groups a user is a direct member of (does not recurse nested groups)

Inputs: username (required), target.

ad_ldap_queryC

Run an LDAP query against the DC. Returns matching objects with specified attributes.

Inputs: filter (required), limit, target, attributes, +1 more.

ad_list_service_accountsB

List service accounts (gMSAs and accounts with "svc" in name)

Inputs: filter, target.

ad_run_commandA

Run an arbitrary PowerShell command on the target DC. WARNING: DANGEROUS - disabled by default. Set AD_ENABLE_RUN_COMMAND=true to enable. All executions are audit logged.

Inputs: command (required), target.

ad_test_kerberos_authC

Test Kerberos authentication by requesting a TGT for a user. Returns success/failure and ticket info.

Inputs: password (required), username (required), target.

ad_test_ldap_bindC

Test LDAP simple bind authentication. Returns success/failure.

Inputs: password (required), username (required), target, useLdaps.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: Kerberos testing, LDAP bind testing, group lookup, service-account listing, security-event retrieval, WinRM diagnosis, command execution, DC info, and generic LDAP query. The main overlap is that ad_ldap_query can be used to retrieve users, groups, or service accounts, making it somewhat interchangeable with ad_get_user_groups and ad_list_service_accounts.

    Naming Consistency5/5

    All tool names use the same ad_ prefix followed by a readable verb_noun or verb_resource pattern. The convention is consistent across test, get, list, diagnose, run, and query operations.

    Tool Count5/5

    Nine tools is a well-scoped set for an AD diagnostics and administration server. Each tool covers a distinct operational area without excessive fragmentation.

    Completeness3/5

    The surface covers diagnostics, authentication testing, read-only directory queries, and emergency command execution. However, common AD lifecycle operations such as creating/disabling users, resetting passwords, unlocking accounts, and modifying group membership are missing from the safe tool surface, leaving ad_run_command as the only write path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Active Directory enumeration and abuse operations through the bloodyAD tool. Supports LDAP queries, user/group management, DNS operations, and security testing directly from AI assistants.
      15
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables LLMs to perform Active Directory penetration testing using tools like NetExec, Bloodhound, Nmap, Certipy, and John the Ripper. Automates vulnerability discovery, attack path analysis, and documentation generation for security assessments.
      26
      7
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Provides AI assistants with unified access to on-prem Active Directory via LDAP and Azure AD / Entra ID through the Microsoft Graph API. It enables comprehensive management and search of users, groups, computers, and cloud devices using 18 specialized tools.
      18
      -
    • A
      license
      A
      quality
      B
      maintenance
      Lets an AI agent read and change on-premises Active Directory by writing short JavaScript scripts that run in a network-isolated sandbox against a chosen domain. Runs on Windows as the logged-on user, over Kerberos, with tools for executing scripts, searching the domain's schema catalogue, querying Microsoft Learn docs, and managing domain connections and Group Policy objects.
      6
      21 npm
      MIT