Skills MCP AD

Multi-Client Active Directory MCP Server - Enterprise AD Management via AI

About • Architecture • Quick Start • Tools • Examples • Configuration

📖 About the Project

Skills MCP AD is a production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude, ChatGPT, and Gemini to securely manage Active Directory environments.

Built by Skills IT and battle-tested in real MSP (Managed Service Provider) operations, this MCP delivers:

✨ 45 comprehensive tools for complete AD lifecycle management 🏢 Multi-client architecture - manage multiple AD domains from a single codebase 🔒 Enterprise-grade security - Bearer Token authentication with audit logging ⚡ Production-tested - deployed in real-world MSP environments 🚀 Easy scaling - add new AD domains in minutes with automated scripts

Why Skills MCP AD?

For Managed Service Providers (MSPs):

Manage multiple client Active Directory domains from one platform
Isolate configurations and credentials per client
Scale effortlessly as your client base grows
Reduce AD management overhead by 70%

For IT Teams:

AI-powered AD operations via natural language
Comprehensive toolset covering users, groups, OUs, computers, GPOs
Streamable HTTP transport compatible with Claude Code and Gemini
Automated onboarding/offboarding workflows

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                     Claude / ChatGPT / Gemini                           │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ MCP Protocol (Streamable HTTP)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Skills MCP AD                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Users     │  │   Groups    │  │     OUs     │  │  Computers  │    │
│  │  (14 tools) │  │  (10 tools) │  │  (8 tools)  │  │  (7 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Password   │  │    GPOs     │  │   Search    │  │   Reports   │    │
│  │  (4 tools)  │  │  (3 tools)  │  │  (2 tools)  │  │  (5 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ LDAP/LDAPS Protocol
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       Active Directory                                  │
│                    (Windows Server / Samba AD)                          │
└─────────────────────────────────────────────────────────────────────────┘

🏗️ Multi-Client Architecture

The game-changer for MSPs: Skills MCP AD's unique architecture allows you to manage multiple Active Directory domains from a single codebase.

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│                         .base-code/                                     │
│                    (Shared Codebase)                                    │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │ Source Code (Python, FastAPI, LDAP3) - 45 Tools                 │   │
│  │ Single point of maintenance and updates                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
         │                          │                          │
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Client A       │      │  Client B       │      │  Client C       │
│  Port: 8850     │      │  Port: 8851     │      │  Port: 8852     │
│  Token: xxx     │      │  Token: yyy     │      │  Token: zzz     │
│  Config:        │      │  Config:        │      │  Config:        │
│  ad-config.json │      │  ad-config.json │      │  ad-config.json │
└─────────────────┘      └─────────────────┘      └─────────────────┘
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  AD Domain A    │      │  AD Domain B    │      │  AD Domain C    │
│  company-a.com  │      │  company-b.com  │      │  company-c.com  │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Key Benefits

✅ Single Codebase - Update once, deploy everywhere ✅ Isolated Configurations - Each client has separate credentials and tokens ✅ Independent Ports - Run multiple instances simultaneously ✅ Easy Scaling - Add new clients in under 2 minutes ✅ Cost Efficient - One deployment handles unlimited AD domains

Directory Structure

active-directory/
├── .base-code/              # Shared source code (this repo)
│   ├── src/                 # Python MCP implementation
│   ├── requirements.txt     # Dependencies
│   └── README.md            # This file
│
├── client-a/                # Client A instance
│   └── ad-config/
│       └── ad-config.json   # Client A AD credentials & config
│
├── client-b/                # Client B instance
│   └── ad-config/
│       └── ad-config.json   # Client B AD credentials & config
│
└── scripts/
    └── install-client.sh    # Script to add new clients

💼 Need Help with Active Directory or AI?

Skills IT - Technology Solutions specializes in IT infrastructure and has deep expertise in Active Directory and Windows Server. Our team has expertise in Artificial Intelligence and Model Context Protocol (MCP), offering complete solutions for automation and system integration.

Our Services:

✅ Active Directory consulting and implementation

✅ Custom MCP development for your infrastructure

✅ AI integration with corporate systems

✅ User and group management automation

✅ Specialized training and support

📞 WhatsApp/Phone: +55 63 3224-4925 - Brazil 🇧🇷 🌐 Website: skillsit.com.br 📧 Email: contato@skillsit.com.br

"Transforming infrastructure into intelligence"

🚀 Quick Start

Prerequisites

Python 3.11+ or Docker
LDAP access to Active Directory
Service account with appropriate AD permissions

Installation (Docker - Recommended)

# 1. Clone the repository
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Configure your Active Directory connection
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD server details

# 3. Start the server
docker-compose up -d

# 4. Verify it's running
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

Expected response:

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "timestamp": "2025-12-09T10:00:00.000Z"
}

Installation (Python)

# 1. Clone and set up virtual environment
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure Active Directory
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD credentials

# 4. Run the server
python -m src.server_http

Connect to Claude Code

# Add MCP server to Claude Code
claude mcp add --transport http ad http://localhost:8850/mcp \
  --headers "Authorization: Bearer your_token_here"

Connect to Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "ad": {
      "httpUrl": "http://localhost:8850/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      },
      "timeout": 30000
    }
  }
}

🧰 Tools (45)

Skills MCP AD provides 45 comprehensive tools organized by functional area:

👥 User Management (14 tools)

Tool	Description	Write Operation
`list_users`	List domain users with filtering	❌ Read
`get_user`	Get detailed user information	❌ Read
`search_user`	Search users by attributes	❌ Read
`get_current_user`	Get authenticated user info	❌ Read
`create_user`	Create new user account	✅ Write
`update_user`	Update user attributes	✅ Write
`delete_user`	Remove user from AD	✅ Write
`enable_user`	Enable user account	✅ Write
`disable_user`	Disable user account	✅ Write
`unlock_user`	Unlock locked account	✅ Write
`add_user_to_groups`	Add user to multiple groups	✅ Write
`remove_user_from_groups`	Remove user from groups	✅ Write
`get_user_groups`	Get user's group memberships	❌ Read
`verify_user_credentials`	Authenticate user credentials	❌ Read

🔐 Password Management (4 tools)

Tool	Description	Write Operation
`reset_password`	Reset user password	✅ Write
`set_password`	Set new password	✅ Write
`force_password_change`	Force password change at next login	✅ Write
`check_password_expiry`	Check password expiration date	❌ Read

🗂️ Group Management (10 tools)

Tool	Description	Write Operation
`list_groups`	List domain groups	❌ Read
`get_group`	Get detailed group information	❌ Read
`search_group`	Search groups by attributes	❌ Read
`create_group`	Create new security/distribution group	✅ Write
`update_group`	Update group attributes	✅ Write
`delete_group`	Remove group from AD	✅ Write
`add_group_member`	Add member to group	✅ Write
`remove_group_member`	Remove member from group	✅ Write
`get_group_members`	List group members (recursive)	❌ Read
`get_nested_groups`	Analyze nested group structure	❌ Read

🏢 Organizational Units (8 tools)

Tool	Description	Write Operation
`list_ous`	List OUs with hierarchy	❌ Read
`get_ou`	Get OU details	❌ Read
`create_ou`	Create new OU	✅ Write
`update_ou`	Update OU attributes	✅ Write
`delete_ou`	Remove empty OU	✅ Write
`move_object`	Move object between OUs	✅ Write
`get_ou_contents`	List contents of OU	❌ Read
`get_ou_tree`	Get OU hierarchy tree	❌ Read

💻 Computer Management (7 tools)

Tool	Description	Write Operation
`list_computers`	List computer accounts	❌ Read
`get_computer`	Get computer details	❌ Read
`create_computer`	Create computer object	✅ Write
`delete_computer`	Remove computer account	✅ Write
`disable_computer`	Disable computer account	✅ Write
`get_stale_computers`	Find inactive computers (90+ days)	❌ Read
`reset_computer_password`	Reset computer account password	✅ Write

🎯 Group Policy Objects (3 tools)

Tool	Description	Write Operation
`list_gpos`	List domain GPOs	❌ Read
`get_gpo`	Get GPO details	❌ Read
`get_gpo_links`	Get GPO link information	❌ Read

🔍 Search & Query (2 tools)

Tool	Description	Write Operation
`search_ad`	Generic LDAP search with custom filters	❌ Read
`advanced_search`	Complex search with multiple criteria	❌ Read

📊 Reporting & Audit (5 tools)

Tool	Description	Write Operation
`get_domain_info`	Domain information and policies	❌ Read
`get_domain_admins`	List Domain Admins members	❌ Read
`get_locked_users`	List locked user accounts	❌ Read
`get_inactive_users`	Users inactive for N days	❌ Read
`get_disabled_users`	List disabled accounts	❌ Read

💡 Usage Examples

Employee Onboarding

"Create a new user John Smith with username jsmith, email jsmith@company.com,
add to Sales group and VPN-Users group, and set password to Welcome2025!
with password change required at first login"

AI executes:

create_user - Creates user in default OU
add_user_to_groups - Adds to Sales and VPN-Users
force_password_change - Enforces password change

Employee Offboarding

"Disable user carlos.souza, remove from all groups,
and move to Terminated-Users OU"

AI executes:

disable_user - Disables account
get_user_groups - Lists current groups
remove_user_from_groups - Removes all memberships
move_object - Moves to appropriate OU

Password Reset

"Reset password for maria.santos to TempPass123!
and require password change at next login"

AI executes:

unlock_user - Unlocks if locked
reset_password - Sets new password
force_password_change - Enforces change policy

Security Audit

"Show me all Domain Admins and users who haven't
logged in for more than 90 days"

AI executes:

get_domain_admins - Lists privileged accounts
get_inactive_users - Finds stale accounts (90+ days)

Bulk User Creation

"Create these users in the Finance group with password Company@2025
and force password change:
- Ana Costa (ana.costa)
- Bruno Lima (bruno.lima)
- Carla Dias (carla.dias)"

AI executes:

create_user - Creates each user
set_password - Sets initial password
add_user_to_groups - Adds to Finance group
force_password_change - Enforces policy

Stale Computer Cleanup

"Find all computers that haven't connected to the domain
in 6 months and show their details"

AI executes:

get_stale_computers - Finds inactive computers (180+ days)
get_computer - Gets details for each

⚙️ Configuration

Configuration File Structure

Create ad-config/ad-config.json:

{
  "ldap_server": "ldap://dc.yourdomain.com",
  "ldap_port": 389,
  "use_ssl": false,
  "base_dn": "DC=yourdomain,DC=com",
  "bind_user": "CN=MCPService,CN=Users,DC=yourdomain,DC=com",
  "bind_password": "YourSecurePassword123!",
  "default_user_ou": "OU=Users,DC=yourdomain,DC=com",
  "default_group_ou": "OU=Groups,DC=yourdomain,DC=com",
  "default_computer_ou": "OU=Computers,DC=yourdomain,DC=com",
  "auth_token": "your_secure_bearer_token_here"
}

Configuration Parameters

Parameter	Description	Required	Default
`ldap_server`	LDAP server URL (ldap:// or ldaps://)	✅ Yes	-
`ldap_port`	LDAP port (389 or 636 for SSL)	✅ Yes	389
`use_ssl`	Use LDAPS (recommended for production)	❌ No	false
`base_dn`	Base Distinguished Name for domain	✅ Yes	-
`bind_user`	Service account DN	✅ Yes	-
`bind_password`	Service account password	✅ Yes	-
`default_user_ou`	Default OU for user creation	❌ No	CN=Users
`default_group_ou`	Default OU for group creation	❌ No	CN=Users
`default_computer_ou`	Default OU for computer creation	❌ No	CN=Computers
`auth_token`	Bearer token for MCP authentication	✅ Yes	-

SSL/TLS Configuration (Production)

For production deployments, use LDAPS:

{
  "ldap_server": "ldaps://dc.yourdomain.com",
  "ldap_port": 636,
  "use_ssl": true,
  "validate_cert": true,
  "ca_cert_path": "/path/to/ca-certificate.pem"
}

Service Account Permissions

The service account (bind_user) requires these Active Directory permissions:

Read Operations (Minimum):

✅ Read all properties - on Domain root
✅ List contents - on Domain root

Write Operations (If needed):

✅ Create/Delete User objects - on Users OU
✅ Create/Delete Group objects - on Groups OU
✅ Create/Delete Computer objects - on Computers OU
✅ Reset Password - on Users OU
✅ Write all properties - on specific OUs

Security Best Practices:

Create a dedicated service account (e.g., MCPService)
Grant minimum permissions required for your use case
Use LDAPS in production
Rotate bind_password and auth_token regularly
Restrict network access to MCP server

🏢 Multi-Client Management

Adding New Clients

Use the included script to add new AD domains in minutes:

# Syntax: ./scripts/install-client.sh <slug> <name> <port>
cd /opt/mcp-servers/active-directory

# Example: Add ACME Corporation on port 8853
./scripts/install-client.sh acme-corp "ACME Corporation" 8853

What the script does:

Creates client directory structure: acme-corp/ad-config/
Generates configuration template: ad-config.json
Creates PM2 process configuration
Registers new MCP instance on specified port

Port Allocation Strategy

Standard port allocation for multi-client deployments:

Client	Port	Process Name
Client 1	8850	mcp-ad-client1
Client 2	8851	mcp-ad-client2
Client 3	8852	mcp-ad-client3
Client N	8850+N	mcp-ad-clientN

Configuration Isolation

Each client has completely isolated:

✅ AD credentials (bind_user, bind_password)
✅ Authentication tokens (auth_token)
✅ LDAP connection settings
✅ Default OUs for object creation

Process Management (PM2)

# List all MCP AD instances
pm2 list | grep mcp-ad

# View logs for specific client
pm2 logs mcp-ad-client1

# Restart specific client
pm2 restart mcp-ad-client1

# Restart all AD MCP instances
pm2 restart all

Updating Shared Codebase

When updating .base-code/, all clients automatically use the new code:

cd .base-code/
git pull origin main

# Restart all instances to apply updates
pm2 restart all

🔐 Security

Authentication

All requests require Bearer Token authentication:

Authorization: Bearer your_secure_token_here

Generate secure tokens:

# Linux/Mac
openssl rand -hex 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Security Best Practices

✅ Use LDAPS in production - Encrypt LDAP traffic (port 636) ✅ Rotate credentials - Change auth_token and bind_password quarterly ✅ Minimum permissions - Service account should have least privilege ✅ Network restrictions - Firewall MCP server to allowed IPs only ✅ Audit logging - Enable detailed logging for compliance ✅ Secret management - Use environment variables or secrets manager

Audit Logging

All operations are logged with:

⏰ Timestamp
👤 Authenticated user/token
🎯 Operation performed (tool name + parameters)
✅ Result (success/failure)
🌐 Source IP address

View logs:

# Docker deployment
docker-compose logs -f skills-mcp-ad

# Python deployment
tail -f logs/mcp-ad.log

🧪 Testing

Health Check

# Test server health and LDAP connectivity
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

Expected response:

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "base_dn": "DC=yourdomain,DC=com",
  "timestamp": "2025-12-09T10:00:00.000Z",
  "tools_count": 45
}

Test MCP Protocol

# List available tools
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Test User Listing

# List domain users
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_users",
      "arguments": {
        "max_results": 10
      }
    },
    "id": 2
  }'

🔧 Troubleshooting

Common Issues

Problem	Cause	Solution
`Connection refused`	Server not running	Check Docker: `docker-compose ps` or Python process
`401 Unauthorized`	Invalid token	Verify `auth_token` in config matches request header
`LDAP bind failed`	Invalid AD credentials	Check `bind_user` and `bind_password` in config
`LDAP server unreachable`	Network/firewall	Test connectivity: `telnet dc.domain.com 389`
`Insufficient permissions`	Service account lacks rights	Grant required AD permissions to `bind_user`
`SSL certificate error`	Invalid/self-signed cert	Set `validate_cert: false` or provide valid CA cert

Debug Mode

Enable detailed LDAP operation logging:

Docker:

# docker-compose.yml
environment:
  - LOG_LEVEL=DEBUG

Python:

export LOG_LEVEL=DEBUG
python -m src.server_http

Verify LDAP Connectivity

# Test LDAP bind from command line
ldapsearch -H ldap://dc.domain.com:389 \
  -D "CN=MCPService,CN=Users,DC=domain,DC=com" \
  -W \
  -b "DC=domain,DC=com" \
  "(objectClass=domain)"

Check Port Availability

# Linux/Mac
lsof -i :8850

# Windows
netstat -an | findstr :8850

🤝 Contributing

We welcome contributions from the community! Whether it's bug reports, feature requests, or code contributions.

Development Setup

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 3. Install development dependencies
pip install -r requirements-dev.txt

# 4. Configure test AD (or use Samba AD test container)
cp ad-config/ad-config.example.json ad-config/ad-config.json

# 5. Run tests
pytest tests/ -v

# 6. Run linter
ruff check .

# 7. Run formatter
black .

Testing Changes

# Run specific test categories
pytest tests/test_user_tools.py -v
pytest tests/test_group_tools.py -v
pytest tests/test_security.py -v

# Run with coverage
pytest --cov=src --cov-report=html

Commit Standards

We follow Conventional Commits:

feat: add GPO management tools
fix: resolve LDAP timeout issue
docs: update configuration examples
refactor: improve error handling in user tools
test: add integration tests for password reset

Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request with clear description

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

You are free to:

✅ Use commercially
✅ Modify
✅ Distribute
✅ Use privately

🙏 Acknowledgments

Built with Model Context Protocol (MCP) SDK
LDAP integration powered by ldap3 library
HTTP transport via FastAPI
Inspired by the need for better AD automation in MSP operations

📞 Support

Get Help

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: contato@skillsit.com.br
🌐 Website: skillsit.com.br

About Skills IT

Skills IT - Soluções em Tecnologia is a Brazilian technology company specializing in MSP solutions and AI-powered automation tools.

We build MCP servers that empower IT teams and MSPs to manage their infrastructure more efficiently through AI assistants.

Our MCP Ecosystem

MCP	Description	Repository
Skills-MCP-AD	Active Directory Management	GitHub
Skills-MCP-GLPI	ITSM & Asset Management	GitHub
Skills-MCP-Hudu	IT Documentation	GitHub
skills-mcp-whm-pro	WHM/cPanel Hosting	GitHub

Contact

📱 Phone: +55 (51) 98049-2520
📧 Email: contato@skillsit.com.br
🌐 Website: skillsit.com.br
💼 GitHub: @DevSkillsIT
📍 Location: Canoas/RS, Brazil 🇧🇷

Made with ❤️ by Skills IT - Soluções em TI - BRAZIL

Empowering MSPs with intelligent automation

⬆ Back to Top

Skills MCP AD

Multi-Client Active Directory MCP Server - Enterprise AD Management via AI

About • Architecture • Quick Start • Tools • Examples • Configuration

📖 About the Project

Skills MCP AD is a production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude, ChatGPT, and Gemini to securely manage Active Directory environments.

Built by Skills IT and battle-tested in real MSP (Managed Service Provider) operations, this MCP delivers:

Why Skills MCP AD?

For Managed Service Providers (MSPs):

Manage multiple client Active Directory domains from one platform
Isolate configurations and credentials per client
Scale effortlessly as your client base grows
Reduce AD management overhead by 70%

For IT Teams:

AI-powered AD operations via natural language
Comprehensive toolset covering users, groups, OUs, computers, GPOs
Streamable HTTP transport compatible with Claude Code and Gemini
Automated onboarding/offboarding workflows

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                     Claude / ChatGPT / Gemini                           │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ MCP Protocol (Streamable HTTP)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Skills MCP AD                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Users     │  │   Groups    │  │     OUs     │  │  Computers  │    │
│  │  (14 tools) │  │  (10 tools) │  │  (8 tools)  │  │  (7 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Password   │  │    GPOs     │  │   Search    │  │   Reports   │    │
│  │  (4 tools)  │  │  (3 tools)  │  │  (2 tools)  │  │  (5 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ LDAP/LDAPS Protocol
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       Active Directory                                  │
│                    (Windows Server / Samba AD)                          │
└─────────────────────────────────────────────────────────────────────────┘

🏗️ Multi-Client Architecture

The game-changer for MSPs: Skills MCP AD's unique architecture allows you to manage multiple Active Directory domains from a single codebase.

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│                         .base-code/                                     │
│                    (Shared Codebase)                                    │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │ Source Code (Python, FastAPI, LDAP3) - 45 Tools                 │   │
│  │ Single point of maintenance and updates                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
         │                          │                          │
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Client A       │      │  Client B       │      │  Client C       │
│  Port: 8850     │      │  Port: 8851     │      │  Port: 8852     │
│  Token: xxx     │      │  Token: yyy     │      │  Token: zzz     │
│  Config:        │      │  Config:        │      │  Config:        │
│  ad-config.json │      │  ad-config.json │      │  ad-config.json │
└─────────────────┘      └─────────────────┘      └─────────────────┘
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  AD Domain A    │      │  AD Domain B    │      │  AD Domain C    │
│  company-a.com  │      │  company-b.com  │      │  company-c.com  │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Key Benefits

Directory Structure

active-directory/
├── .base-code/              # Shared source code (this repo)
│   ├── src/                 # Python MCP implementation
│   ├── requirements.txt     # Dependencies
│   └── README.md            # This file
│
├── client-a/                # Client A instance
│   └── ad-config/
│       └── ad-config.json   # Client A AD credentials & config
│
├── client-b/                # Client B instance
│   └── ad-config/
│       └── ad-config.json   # Client B AD credentials & config
│
└── scripts/
    └── install-client.sh    # Script to add new clients

💼 Need Help with Active Directory or AI?

Skills IT - Technology Solutions specializes in IT infrastructure and has deep expertise in Active Directory and Windows Server. Our team has expertise in Artificial Intelligence and Model Context Protocol (MCP), offering complete solutions for automation and system integration.

Our Services:

✅ Active Directory consulting and implementation

✅ Custom MCP development for your infrastructure

✅ AI integration with corporate systems

✅ User and group management automation

✅ Specialized training and support

📞 WhatsApp/Phone: +55 63 3224-4925 - Brazil 🇧🇷 🌐 Website: skillsit.com.br 📧 Email: contato@skillsit.com.br

"Transforming infrastructure into intelligence"

🚀 Quick Start

Prerequisites

Python 3.11+ or Docker
LDAP access to Active Directory
Service account with appropriate AD permissions

Installation (Docker - Recommended)

# 1. Clone the repository
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Configure your Active Directory connection
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD server details

# 3. Start the server
docker-compose up -d

# 4. Verify it's running
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

Expected response:

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "timestamp": "2025-12-09T10:00:00.000Z"
}

Installation (Python)

# 1. Clone and set up virtual environment
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure Active Directory
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD credentials

# 4. Run the server
python -m src.server_http

Connect to Claude Code

# Add MCP server to Claude Code
claude mcp add --transport http ad http://localhost:8850/mcp \
  --headers "Authorization: Bearer your_token_here"

Connect to Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "ad": {
      "httpUrl": "http://localhost:8850/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      },
      "timeout": 30000
    }
  }
}

🧰 Tools (45)

Skills MCP AD provides 45 comprehensive tools organized by functional area:

👥 User Management (14 tools)

Tool	Description	Write Operation
`list_users`	List domain users with filtering	❌ Read
`get_user`	Get detailed user information	❌ Read
`search_user`	Search users by attributes	❌ Read
`get_current_user`	Get authenticated user info	❌ Read
`create_user`	Create new user account	✅ Write
`update_user`	Update user attributes	✅ Write
`delete_user`	Remove user from AD	✅ Write
`enable_user`	Enable user account	✅ Write
`disable_user`	Disable user account	✅ Write
`unlock_user`	Unlock locked account	✅ Write
`add_user_to_groups`	Add user to multiple groups	✅ Write
`remove_user_from_groups`	Remove user from groups	✅ Write
`get_user_groups`	Get user's group memberships	❌ Read
`verify_user_credentials`	Authenticate user credentials	❌ Read

🔐 Password Management (4 tools)

Tool	Description	Write Operation
`reset_password`	Reset user password	✅ Write
`set_password`	Set new password	✅ Write
`force_password_change`	Force password change at next login	✅ Write
`check_password_expiry`	Check password expiration date	❌ Read

🗂️ Group Management (10 tools)

Tool	Description	Write Operation
`list_groups`	List domain groups	❌ Read
`get_group`	Get detailed group information	❌ Read
`search_group`	Search groups by attributes	❌ Read
`create_group`	Create new security/distribution group	✅ Write
`update_group`	Update group attributes	✅ Write
`delete_group`	Remove group from AD	✅ Write
`add_group_member`	Add member to group	✅ Write
`remove_group_member`	Remove member from group	✅ Write
`get_group_members`	List group members (recursive)	❌ Read
`get_nested_groups`	Analyze nested group structure	❌ Read

🏢 Organizational Units (8 tools)

Tool	Description	Write Operation
`list_ous`	List OUs with hierarchy	❌ Read
`get_ou`	Get OU details	❌ Read
`create_ou`	Create new OU	✅ Write
`update_ou`	Update OU attributes	✅ Write
`delete_ou`	Remove empty OU	✅ Write
`move_object`	Move object between OUs	✅ Write
`get_ou_contents`	List contents of OU	❌ Read
`get_ou_tree`	Get OU hierarchy tree	❌ Read

💻 Computer Management (7 tools)

Tool	Description	Write Operation
`list_computers`	List computer accounts	❌ Read
`get_computer`	Get computer details	❌ Read
`create_computer`	Create computer object	✅ Write
`delete_computer`	Remove computer account	✅ Write
`disable_computer`	Disable computer account	✅ Write
`get_stale_computers`	Find inactive computers (90+ days)	❌ Read
`reset_computer_password`	Reset computer account password	✅ Write

🎯 Group Policy Objects (3 tools)

Tool	Description	Write Operation
`list_gpos`	List domain GPOs	❌ Read
`get_gpo`	Get GPO details	❌ Read
`get_gpo_links`	Get GPO link information	❌ Read

🔍 Search & Query (2 tools)

Tool	Description	Write Operation
`search_ad`	Generic LDAP search with custom filters	❌ Read
`advanced_search`	Complex search with multiple criteria	❌ Read

📊 Reporting & Audit (5 tools)

Tool	Description	Write Operation
`get_domain_info`	Domain information and policies	❌ Read
`get_domain_admins`	List Domain Admins members	❌ Read
`get_locked_users`	List locked user accounts	❌ Read
`get_inactive_users`	Users inactive for N days	❌ Read
`get_disabled_users`	List disabled accounts	❌ Read

💡 Usage Examples

Employee Onboarding

"Create a new user John Smith with username jsmith, email jsmith@company.com,
add to Sales group and VPN-Users group, and set password to Welcome2025!
with password change required at first login"

AI executes:

create_user - Creates user in default OU
add_user_to_groups - Adds to Sales and VPN-Users
force_password_change - Enforces password change

Employee Offboarding

"Disable user carlos.souza, remove from all groups,
and move to Terminated-Users OU"

AI executes:

disable_user - Disables account
get_user_groups - Lists current groups
remove_user_from_groups - Removes all memberships
move_object - Moves to appropriate OU

Password Reset

"Reset password for maria.santos to TempPass123!
and require password change at next login"

AI executes:

unlock_user - Unlocks if locked
reset_password - Sets new password
force_password_change - Enforces change policy

Security Audit

"Show me all Domain Admins and users who haven't
logged in for more than 90 days"

AI executes:

get_domain_admins - Lists privileged accounts
get_inactive_users - Finds stale accounts (90+ days)

Bulk User Creation

"Create these users in the Finance group with password Company@2025
and force password change:
- Ana Costa (ana.costa)
- Bruno Lima (bruno.lima)
- Carla Dias (carla.dias)"

AI executes:

create_user - Creates each user
set_password - Sets initial password
add_user_to_groups - Adds to Finance group
force_password_change - Enforces policy

Stale Computer Cleanup

"Find all computers that haven't connected to the domain
in 6 months and show their details"

AI executes:

get_stale_computers - Finds inactive computers (180+ days)
get_computer - Gets details for each

⚙️ Configuration

Configuration File Structure

Create ad-config/ad-config.json:

{
  "ldap_server": "ldap://dc.yourdomain.com",
  "ldap_port": 389,
  "use_ssl": false,
  "base_dn": "DC=yourdomain,DC=com",
  "bind_user": "CN=MCPService,CN=Users,DC=yourdomain,DC=com",
  "bind_password": "YourSecurePassword123!",
  "default_user_ou": "OU=Users,DC=yourdomain,DC=com",
  "default_group_ou": "OU=Groups,DC=yourdomain,DC=com",
  "default_computer_ou": "OU=Computers,DC=yourdomain,DC=com",
  "auth_token": "your_secure_bearer_token_here"
}

Configuration Parameters

Parameter	Description	Required	Default
`ldap_server`	LDAP server URL (ldap:// or ldaps://)	✅ Yes	-
`ldap_port`	LDAP port (389 or 636 for SSL)	✅ Yes	389
`use_ssl`	Use LDAPS (recommended for production)	❌ No	false
`base_dn`	Base Distinguished Name for domain	✅ Yes	-
`bind_user`	Service account DN	✅ Yes	-
`bind_password`	Service account password	✅ Yes	-
`default_user_ou`	Default OU for user creation	❌ No	CN=Users
`default_group_ou`	Default OU for group creation	❌ No	CN=Users
`default_computer_ou`	Default OU for computer creation	❌ No	CN=Computers
`auth_token`	Bearer token for MCP authentication	✅ Yes	-

SSL/TLS Configuration (Production)

For production deployments, use LDAPS:

{
  "ldap_server": "ldaps://dc.yourdomain.com",
  "ldap_port": 636,
  "use_ssl": true,
  "validate_cert": true,
  "ca_cert_path": "/path/to/ca-certificate.pem"
}

Service Account Permissions

The service account (bind_user) requires these Active Directory permissions:

Read Operations (Minimum):

✅ Read all properties - on Domain root
✅ List contents - on Domain root

Write Operations (If needed):

✅ Create/Delete User objects - on Users OU
✅ Create/Delete Group objects - on Groups OU
✅ Create/Delete Computer objects - on Computers OU
✅ Reset Password - on Users OU
✅ Write all properties - on specific OUs

Security Best Practices:

Create a dedicated service account (e.g., MCPService)
Grant minimum permissions required for your use case
Use LDAPS in production
Rotate bind_password and auth_token regularly
Restrict network access to MCP server

🏢 Multi-Client Management

Adding New Clients

Use the included script to add new AD domains in minutes:

# Syntax: ./scripts/install-client.sh <slug> <name> <port>
cd /opt/mcp-servers/active-directory

# Example: Add ACME Corporation on port 8853
./scripts/install-client.sh acme-corp "ACME Corporation" 8853

What the script does:

Creates client directory structure: acme-corp/ad-config/
Generates configuration template: ad-config.json
Creates PM2 process configuration
Registers new MCP instance on specified port

Port Allocation Strategy

Standard port allocation for multi-client deployments:

Client	Port	Process Name
Client 1	8850	mcp-ad-client1
Client 2	8851	mcp-ad-client2
Client 3	8852	mcp-ad-client3
Client N	8850+N	mcp-ad-clientN

Configuration Isolation

Each client has completely isolated:

✅ AD credentials (bind_user, bind_password)
✅ Authentication tokens (auth_token)
✅ LDAP connection settings
✅ Default OUs for object creation

Process Management (PM2)

# List all MCP AD instances
pm2 list | grep mcp-ad

# View logs for specific client
pm2 logs mcp-ad-client1

# Restart specific client
pm2 restart mcp-ad-client1

# Restart all AD MCP instances
pm2 restart all

Updating Shared Codebase

When updating .base-code/, all clients automatically use the new code:

cd .base-code/
git pull origin main

# Restart all instances to apply updates
pm2 restart all

🔐 Security

Authentication

All requests require Bearer Token authentication:

Authorization: Bearer your_secure_token_here

Generate secure tokens:

# Linux/Mac
openssl rand -hex 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Security Best Practices

Audit Logging

All operations are logged with:

⏰ Timestamp
👤 Authenticated user/token
🎯 Operation performed (tool name + parameters)
✅ Result (success/failure)
🌐 Source IP address

View logs:

# Docker deployment
docker-compose logs -f skills-mcp-ad

# Python deployment
tail -f logs/mcp-ad.log

🧪 Testing

Health Check

# Test server health and LDAP connectivity
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

Expected response:

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "base_dn": "DC=yourdomain,DC=com",
  "timestamp": "2025-12-09T10:00:00.000Z",
  "tools_count": 45
}

Test MCP Protocol

# List available tools
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Test User Listing

# List domain users
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_users",
      "arguments": {
        "max_results": 10
      }
    },
    "id": 2
  }'

🔧 Troubleshooting

Common Issues

Problem	Cause	Solution
`Connection refused`	Server not running	Check Docker: `docker-compose ps` or Python process
`401 Unauthorized`	Invalid token	Verify `auth_token` in config matches request header
`LDAP bind failed`	Invalid AD credentials	Check `bind_user` and `bind_password` in config
`LDAP server unreachable`	Network/firewall	Test connectivity: `telnet dc.domain.com 389`
`Insufficient permissions`	Service account lacks rights	Grant required AD permissions to `bind_user`
`SSL certificate error`	Invalid/self-signed cert	Set `validate_cert: false` or provide valid CA cert

Debug Mode

Enable detailed LDAP operation logging:

Docker:

# docker-compose.yml
environment:
  - LOG_LEVEL=DEBUG

Python:

export LOG_LEVEL=DEBUG
python -m src.server_http

Verify LDAP Connectivity

# Test LDAP bind from command line
ldapsearch -H ldap://dc.domain.com:389 \
  -D "CN=MCPService,CN=Users,DC=domain,DC=com" \
  -W \
  -b "DC=domain,DC=com" \
  "(objectClass=domain)"

Check Port Availability

# Linux/Mac
lsof -i :8850

# Windows
netstat -an | findstr :8850

🤝 Contributing

We welcome contributions from the community! Whether it's bug reports, feature requests, or code contributions.

Development Setup

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 3. Install development dependencies
pip install -r requirements-dev.txt

# 4. Configure test AD (or use Samba AD test container)
cp ad-config/ad-config.example.json ad-config/ad-config.json

# 5. Run tests
pytest tests/ -v

# 6. Run linter
ruff check .

# 7. Run formatter
black .

Testing Changes

# Run specific test categories
pytest tests/test_user_tools.py -v
pytest tests/test_group_tools.py -v
pytest tests/test_security.py -v

# Run with coverage
pytest --cov=src --cov-report=html

Commit Standards

We follow Conventional Commits:

feat: add GPO management tools
fix: resolve LDAP timeout issue
docs: update configuration examples
refactor: improve error handling in user tools
test: add integration tests for password reset

Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request with clear description

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

You are free to:

✅ Use commercially
✅ Modify
✅ Distribute
✅ Use privately

🙏 Acknowledgments

Built with Model Context Protocol (MCP) SDK
LDAP integration powered by ldap3 library
HTTP transport via FastAPI
Inspired by the need for better AD automation in MSP operations

📞 Support

Get Help

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: contato@skillsit.com.br
🌐 Website: skillsit.com.br

About Skills IT

Skills IT - Soluções em Tecnologia is a Brazilian technology company specializing in MSP solutions and AI-powered automation tools.

We build MCP servers that empower IT teams and MSPs to manage their infrastructure more efficiently through AI assistants.

Our MCP Ecosystem

MCP	Description	Repository
Skills-MCP-AD	Active Directory Management	GitHub
Skills-MCP-GLPI	ITSM & Asset Management	GitHub
Skills-MCP-Hudu	IT Documentation	GitHub
skills-mcp-whm-pro	WHM/cPanel Hosting	GitHub

Contact

📱 Phone: +55 (51) 98049-2520
📧 Email: contato@skillsit.com.br
🌐 Website: skillsit.com.br
💼 GitHub: @DevSkillsIT
📍 Location: Canoas/RS, Brazil 🇧🇷

Made with ❤️ by Skills IT - Soluções em TI - BRAZIL

Empowering MSPs with intelligent automation

⬆ Back to Top