Skip to main content
Glama
MCP Active Directory Server

MCP Active Directory Server

by AlexLiAtDuo
README.md
# MCP Active Directory Server

[![npm version](https://img.shields.io/npm/v/mcp-active-directory-server.svg)](https://www.npmjs.com/package/mcp-active-directory-server)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)](https://www.microsoft.com/windows)

**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

## 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](https://nodejs.org/)
- **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

```bash
npm install -g mcp-active-directory-server
```

### Install from Source

```bash
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

```bash
# 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:

```bash
# 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:

```powershell
# 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:

```json
{
  "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):

```json
{
  "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](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:
- [GitHub Security Advisories](https://github.com/cisco-sbg/mcp-active-directory-server/security/advisories/new)
- Email: psirt@cisco.com

## 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](https://github.com/cisco-sbg/mcp-active-directory-server/issues) - Bug reports and feature requests
- [Discussions](https://github.com/cisco-sbg/mcp-active-directory-server/discussions) - Questions and community support

## Getting Involved

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup
- Code style guidelines
- Pull request process

## Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [Claude Code](https://claude.ai/code) - AI coding assistant with MCP support
- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Official MCP SDK for TypeScript

## Credits

- **Author**: Cisco Systems, Inc.
- **MCP SDK**: Anthropic

## License

[Apache 2.0](LICENSE) - 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.*

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