MCP Active Directory Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Active Directory Server check why jdoe can't authenticate to the domain"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Active Directory Server
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 |
| Get Domain Controller hostname, OS version, uptime, and list of all DCs in the domain |
| Run LDAP queries with custom filters, search bases, and attribute selection |
| Test Kerberos authentication by requesting a TGT for a specified user |
| Test LDAP/LDAPS simple bind authentication for a user |
| Get all groups (including nested) that a user is a member of |
| List Group Managed Service Accounts (gMSAs) and service accounts |
| Query Windows Security events (4624, 4625, 4768, 4769, 4776) |
| Diagnose WinRM HTTPS configuration on a Domain Controller |
| 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-serverInstall from Source
git clone https://github.com/cisco-sbg/mcp-active-directory-server.git
cd mcp-active-directory-server
npm install
npm run buildConfiguration
The server supports multiple credential sources, checked in order:
Environment variables (recommended for development)
MACHINES.TXT file (for multi-DC environments)
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=password2Then 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.ps1This 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:
Test Kerberos TGT request with
ad_test_kerberos_authTest LDAP bind with
ad_test_ldap_bindCheck recent security events with
ad_get_security_eventsReport specific failure reason (locked account, expired password, etc.)
Audit Service Accounts
"List all service accounts and their last password change"
ad_list_service_accountsReturns 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 60Returns 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_winrmReturns 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 |
WinRM HTTPS Only | Connections use port 5986 with TLS encryption |
Dangerous Tool Disabled |
|
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
GitHub Issues - Bug reports and feature requests
Discussions - Questions and community support
Getting Involved
Contributions are welcome! See CONTRIBUTING.md for:
Development setup
Code style guidelines
Pull request process
Related Projects
Model Context Protocol - The protocol specification
Claude Code - AI coding assistant with MCP support
MCP SDK - Official MCP SDK for TypeScript
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 toolsad_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
Scored across 9 tools
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.
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.
Nine tools is a well-scoped set for an AD diagnostics and administration server. Each tool covers a distinct operational area without excessive fragmentation.
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
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Check whether AI agents can discover, validate, and trust your domain's services.
Governed security assessments, findings and signed reports for your domains, from your AI agent.
Monitors TLS/SSL certificate expiry, DNS resolution, and TCP port status for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.15MIT
- AlicenseCqualityDmaintenanceEnables 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.267MIT
- FlicenseAqualityCmaintenanceProvides 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-
- AlicenseAqualityBmaintenanceLets 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.621 npmMIT