Skip to main content
Glama
DevSkillsIT

Skills MCP AD

by DevSkillsIT
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

📖 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

ad_list_users_with_filters

Usuários e contas de domínio no Active Directory com filtros

❌ Read

ad_get_user_details_by_username

Detalhes completos de usuário específico por username

❌ Read

ad_search_users_by_attributes

Busca de usuários por atributos no AD

❌ 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:

  1. create_user - Creates user in default OU

  2. add_user_to_groups - Adds to Sales and VPN-Users

  3. force_password_change - Enforces password change

Employee Offboarding

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

AI executes:

  1. disable_user - Disables account

  2. get_user_groups - Lists current groups

  3. remove_user_from_groups - Removes all memberships

  4. move_object - Moves to appropriate OU

Password Reset

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

AI executes:

  1. unlock_user - Unlocks if locked

  2. reset_password - Sets new password

  3. 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:

  1. get_domain_admins - Lists privileged accounts

  2. 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:

  1. create_user - Creates each user

  2. set_password - Sets initial password

  3. add_user_to_groups - Adds to Finance group

  4. 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:

  1. get_stale_computers - Finds inactive computers (180+ days)

  2. 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:

  1. Creates client directory structure: acme-corp/ad-config/

  2. Generates configuration template: ad-config.json

  3. Creates PM2 process configuration

  4. 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": "ad_list_users_with_filters",
      "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

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'feat: add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. 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

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

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

Empowering MSPs with intelligent automation

⬆ Back to Top

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DevSkillsIT/Skills-MCP-AD'

If you have feedback or need assistance with the MCP directory API, please join our Discord server