Skills MCP AD MCP Server

How to use

You connect an MCP client to Skill MCP AD using HTTP transport or by running the MCP server locally. Use the HTTP method when you want a remote or centralized MCP endpoint; use the local method when you prefer an in-process setup for testing or tight integration with other Python components.

From your MCP client, authenticate requests with a Bearer token that your server validates. You can perform a wide range of AD operations, such as managing users, groups, OUs, computers, and GPOs, as well as performing searches, reports, and security audits. Start by ensuring your client points to the MCP endpoint http://localhost:8850/mcp for HTTP usage, and supply your token in the Authorization header.

How to install

Prerequisites: ensure you have Python 3.11+ installed, or Docker available on your system. You also need LDAP access to Active Directory with a service account that has appropriate permissions.

Installation (Docker recommended) follows a simple flow: clone the project, configure your AD connection, and start the services with Docker Compose.

Installation (Python) follows an equivalent flow using a virtual environment and the Python package stack, then running the HTTP server entry point.

# Docker installation flow
# 1. Create a working directory and pull the containerized deployment
# 2. Configure your Active Directory connection in ad-config/ad-config.json
# 3. Start the services
# 4. Verify health via HTTP health endpoint

# Python installation flow
# 1. Create a virtual environment
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 in ad-config/ad-config.json
# 4. Run the HTTP server
python -m src.server_http

Configuration

Create the AD configuration file at ad-config/ad-config.json with your LDAP server details, base DN, and a secure bearer token used for MCP authentication.

{
  "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"
}

Security and access

All requests require a Bearer token for authentication. Rotate credentials regularly, use LDAPS in production, and apply the principle of least privilege to the service account. Enable audit logging to keep a trace of operations.

For multi-client deployments, each client operates in isolation with dedicated credentials and tokens. You can run multiple MCP instances on separate ports for different AD domains.

Testing and health checks

Verify the server is healthy and connected to LDAP by querying the health endpoint with your token.

curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

Troubleshooting

If you encounter issues, check connectivity to the LDAP server, verify the MCP authentication token, and review logs for errors related to LDAP binding or permissions. Use the provided health and logs endpoints to pinpoint problems.

Multi-client management and scripting

You can add new client domains using the included script and manage each client with isolated configurations and tokens. Run the client creation script with the appropriate slug, name, and port to provision a new MCP instance for a new AD domain.

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

list_users

List domain users with optional filtering

get_user

Retrieve detailed information for a specific user

search_user

Search users by attributes

get_current_user

Return information about the authenticated user

create_user

Create a new user in the directory

update_user

Update attributes for an existing user

delete_user

Remove a user from the directory

enable_user

Enable a disabled user account

disable_user

Disable an active user account

unlock_user

Unlock a locked user account

add_user_to_groups

Add a user to one or more groups

remove_user_from_groups

Remove a user from one or more groups

get_user_groups

List a user's group memberships

verify_user_credentials

Authenticate user credentials against AD

reset_password

Reset a user's password

set_password

Set a new password for a user

force_password_change

Require password change on next login

check_password_expiry

Check password expiration date for a user

list_groups

List domain groups

get_group

Retrieve detailed information for a group

search_group

Search groups by attributes

create_group

Create a new security or distribution group

update_group

Update group attributes

delete_group

Delete a group from AD

add_group_member

Add a member to a group

remove_group_member

Remove a member from a group

get_group_members

List members of a group (recursive)

get_nested_groups

Analyze nested group structures

list_ous

List organizational units with hierarchy

get_ou

Get details of an OU

create_ou

Create a new OU

update_ou

Update OU attributes

delete_ou

Delete an OU

move_object

Move an object between OUs

get_ou_contents

List contents of an OU

get_ou_tree

Get OU hierarchy tree

list_computers

List computer accounts

get_computer

Get computer details

create_computer

Create a computer object

delete_computer

Remove a computer account

disable_computer

Disable a computer account

get_stale_computers

Find inactive computers (90+ days)

reset_computer_password

Reset computer account password

list_gpos

List GPOs in the domain

get_gpo

Get details of a GPO

get_gpo_links

Get information about GPO links