andreransom58-coder/ad-mcp-server

Active Directory MCP Server

A Model Context Protocol (MCP) server for managing Microsoft Active Directory. This server enables Claude and other MCP clients to interact with Active Directory to perform user management, group operations, and organizational unit administration.

Features

• User Management: Create, modify, enable/disable, and delete user accounts
• Password Operations: Reset passwords with complexity validation
• User Search: Query users by username, email, or other attributes
• LDAPS Support: Secure LDAP connections with SSL/TLS
• Input Validation: Comprehensive validation to prevent LDAP injection
• Audit Logging: Track all AD modifications for compliance

Prerequisites

• Python 3.10 or higher
• Access to an Active Directory environment
• Service account with appropriate AD permissions
• LDAPS configured on your domain controller (recommended)

Installation

1. Clone the repository:

   cd D:\repo1
   

2. Create a virtual environment:

   python -m venv venv
   
   # On Windows:
   venv\Scripts\activate
   
   # On Linux/Mac:
   source venv/bin/activate
   

3. Install dependencies:

   pip install -e .
   
   # Or with uv (faster):
   uv pip install -e .
   

4. Install development dependencies (optional):

   pip install -e ".[dev]"
   

Configuration

1. Copy the environment template:

   copy .env.example .env
   

2. Edit .env with your Active Directory details:

   # Required settings
   AD_SERVER=dc01.example.com
   AD_PORT=636
   AD_USE_SSL=true
   AD_DOMAIN=EXAMPLE
   AD_BASE_DN=DC=example,DC=com
   
   # Service account credentials
   AD_BIND_DN=CN=MCP Service Account,OU=Service Accounts,DC=example,DC=com
   AD_BIND_PASSWORD=your_secure_password_here
   
   # Optional: Windows Integrated Authentication
   AD_USE_INTEGRATED_AUTH=false
   
   # Security settings
   AD_VERIFY_CERT=true
   AD_CERT_PATH=/path/to/ca-cert.pem
   

Service Account Permissions

The service account needs the following Active Directory permissions:

• User Management: Create, modify, delete user objects in target OUs
• Password Reset: Reset password permission
• Read Access: Read all user attributes
• Group Management: Modify group memberships (optional)

Usage

Running the Server

Standalone Mode

python -m src.main

With MCP Inspector (for testing)

npx @modelcontextprotocol/inspector python -m src.main

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "active-directory": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "D:\\repo1"
    }
  }
}

Note: Ensure your .env file is properly configured in the project directory.

Available Tools

create_user

Create a new user in Active Directory.

Parameters:

• username (required): sAMAccountName, max 20 characters
• first_name (required): First name
• last_name (required): Last name
• ou_path (required): Full DN of OU (e.g., OU=Users,DC=example,DC=com)
• password (required): Initial password (min 12 chars, complexity required)
• email (optional): Email address
• upn (optional): User Principal Name
• enabled (optional): Enable account (default: true)
• title (optional): Job title
• department (optional): Department

Example:

Create a new user with username "jdoe", first name "John", last name "Doe"
in OU=Users,DC=example,DC=com with password "SecurePass123!"

get_user

Get user information from Active Directory.

Parameters (at least one required):

• username: sAMAccountName
• user_dn: Distinguished name
• email: Email address

Example:

Get user information for username "jdoe"

modify_user

Modify user attributes.

Parameters:

• user_dn (required): Distinguished name of user
• display_name (optional): Display name
• mail (optional): Email address
• telephone_number (optional): Phone number
• title (optional): Job title
• department (optional): Department
• company (optional): Company name

Example:

Update the email for user "CN=John Doe,OU=Users,DC=example,DC=com"
to "john.doe@example.com"

disable_user

Disable a user account.

Parameters:

• user_dn (required): Distinguished name of user

Example:

Disable user account "CN=John Doe,OU=Users,DC=example,DC=com"

enable_user

Enable a user account.

Parameters:

• user_dn (required): Distinguished name of user

reset_password

Reset a user's password.

Parameters:

• user_dn (required): Distinguished name of user
• new_password (required): New password (min 12 chars, complexity required)

Example:

Reset password for "CN=John Doe,OU=Users,DC=example,DC=com" to "NewSecure123!"

delete_user

Delete a user from Active Directory.

Parameters:

• user_dn (required): Distinguished name of user

Example:

Delete user "CN=Test User,OU=Users,DC=example,DC=com"

search_users

Search for users in Active Directory.

Parameters:

• username (optional): Filter by username
• email (optional): Filter by email
• enabled_only (optional): Only return enabled accounts (default: false)
• max_results (optional): Maximum results (default: 100)

Example:

Search for all enabled users in the domain

Security Considerations

LDAP Injection Prevention

All user inputs are validated and sanitized to prevent LDAP injection attacks. Special LDAP characters are properly escaped.

Secure Connections

Always use LDAPS (port 636) in production. The server enforces SSL/TLS by default and validates certificates.

Credential Management

• Never commit .env file to version control
• Use a dedicated service account with least-privilege permissions
• Rotate service account passwords regularly
• Consider using Azure Key Vault or HashiCorp Vault in production

Audit Logging

All AD modifications are logged with timestamps and affected objects. Check logs/ad-audit.log for audit trail.

Development

Running Tests

pytest tests/

Code Formatting

black src/

Type Checking

mypy src/

Linting

ruff check src/

Troubleshooting

Connection Issues

• Verify AD server hostname and port
• Check firewall rules allow LDAPS (port 636)
• Ensure service account credentials are correct
• Test LDAP connection with ldp.exe or ldapsearch

Certificate Errors

• If using self-signed certificates, set AD_VERIFY_CERT=false (not recommended for production)
• Or provide path to CA certificate in AD_CERT_PATH

Permission Errors

• Verify service account has required permissions in AD
• Check delegation of control for target OUs
• Review AD security logs for access denied events

Password Complexity Errors

• Ensure passwords meet domain password policy
• Default requirement: min 12 chars, 3 of 4 character types
• Adjust PASSWORD_MIN_LENGTH in .env if needed

Project Structure

D:\repo1\
├── src/
│   ├── main.py                 # MCP server entry point
│   ├── ad_connector.py         # LDAP connection management
│   ├── types.py                # Type definitions
│   ├── tools/
│   │   └── user_tools.py       # User management functions
│   └── utils/
│       ├── validators.py       # Input validation
│       ├── ldap_utils.py       # LDAP helpers
│       └── formatters.py       # Output formatting
├── tests/                      # Test suite
├── logs/                       # Log files
├── pyproject.toml              # Project configuration
├── .env.example                # Environment template
└── README.md                   # This file

Contributing

Contributions are welcome! Please:

1. Follow PEP 8 style guidelines
2. Add type hints to all functions
3. Write tests for new features
4. Update documentation

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the file for detailed implementation notes
• Review logs in logs/ directory
• Open an issue on GitHub

Roadmap

Future enhancements:

• Group management tools (create, modify, add/remove members)
• OU management (create, move objects)
• Computer account management
• Bulk user operations
• Resource and prompt templates
• PowerShell integration for advanced operations
• Support for Azure AD / Entra ID