ActiveDirectoryMCP

A Model Context Protocol (MCP) server that exposes Active Directory (LDAP) administration and auditing to MCP clients such as Claude Desktop, Claude Code and Cursor. It offers 45 tools for users, groups, computers, organizational units, domain security reporting and server diagnostics, over stdio or authenticated HTTP.

Status: the repository is public; the v1.0.0 release is not tagged yet. The server is tested against a mocked LDAP harness (unit and end-to-end tests) and against an OpenLDAP lab, which is not Active Directory. Checks against a live Active Directory domain are the responsibility of the operator before relying on it in production.

What it does and what it does not do by default

• Read tools (list, get, report, audit, diagnostics) work out of the box.
• The server is read-only by default. Create, modify, enable, disable, reset and membership tools

are refused until security.allow_writes is true. Delete tools additionally need security.allow_destructive.

• The HTTP transport refuses to start without an API key and answers 401 to every request that

does not present one (only GET /health is open).

• List and report tools return at most security.max_list_results entries (default 1000).
• Outbound connections go only to the directory server you configure and, if you configure Azure Key

Vault, to Azure Key Vault and the Azure identity endpoints. Logs and the optional audit file are written locally.

Requirements

• Python 3.11 or newer
• uv
• Network access to a domain controller; LDAPS is strongly recommended
• A dedicated service account with the minimum rights you need (see Service account below)
• Docker, only for the container deployment

Quickstart (stdio)

git clone https://github.com/alpadalar/ActiveDirectoryMCP.git
cd ActiveDirectoryMCP
uv sync --locked                 # add --extra azure for Azure Key Vault support
uv run pytest -q                 # optional: unit tests, no directory needed
cp ad-config/config.example.json ad-config/ad-config.json

Edit ad-config/ad-config.json before the first start: set active_directory.server, domain, base_dn and bind_dn for your domain. The example uses ldaps:// URLs, which security.require_secure_connection (true by default) requires; for an internal CA add security.ca_cert_file with the path of your CA certificate (see TLS), otherwise the system trust store is used. The example contains no key_vault section; add one only if you use Azure Key Vault. With the placeholder host names it starts but cannot connect to a directory until you edit it.

Provide the bind credential through the environment (or Key Vault, see Credentials) and start the server:

export AD_BIND_DN='CN=service-account,OU=Service Accounts,DC=example,DC=com'
read -rs AD_PASSWORD && export AD_PASSWORD     # type the password, it is not echoed
AD_MCP_CONFIG=ad-config/ad-config.json uv run activedirectory-mcp

The stdio server speaks MCP on stdin/stdout, so it waits for a client and prints log lines on the console. It has no --help; the only required setting is the AD_MCP_CONFIG environment variable. Connect it from an MCP client as shown in Connect an MCP client.

A failed initial directory connection is logged but does not stop the server, so the tool list is available even when the domain controller cannot be reached; tool calls then return errors.

Run over HTTP

The HTTP transport requires an API key. Generate one and export it:

export AD_MCP_HTTP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
export AD_BIND_DN='CN=service-account,OU=Service Accounts,DC=example,DC=com'
read -rs AD_PASSWORD && export AD_PASSWORD
AD_MCP_CONFIG=ad-config/ad-config.json uv run python -m active_directory_mcp.server_http \
  --host 127.0.0.1 --port 8813 --path /activedirectory-mcp

Flags: --host (default 0.0.0.0), --port (default 8813), --path (default /activedirectory-mcp), --config (overrides AD_MCP_CONFIG). Binding to 127.0.0.1 is the safe choice on a workstation; the default 0.0.0.0 listens on every interface.

Check the server (the endpoint accepts either header):

curl -s http://127.0.0.1:8813/health                       # 200, no key needed
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8813/activedirectory-mcp   # 401
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $AD_MCP_HTTP_API_KEY" \
  http://127.0.0.1:8813/activedirectory-mcp                 # not 401 (a plain GET gets 406)
curl -s -o /dev/null -w '%{http_code}\n' -H "X-API-Key: $AD_MCP_HTTP_API_KEY" \
  http://127.0.0.1:8813/activedirectory-mcp                 # not 401

/health returns {"status", "server", "version"}, performs no LDAP query and reveals no hostnames or credentials. For an LDAP-aware status call the health or test_connection tool through an MCP client. To avoid keeping the plaintext key in the server environment, supply its SHA-256 digest instead; see Security configuration.

The launcher scripts start_server.sh, start_http_server.sh and their .bat equivalents load a .env file (template: .env.example) and start the same entry points. They print progress messages to stdout, so do not use start_server.sh as an MCP client command: use the uv run activedirectory-mcp commands shown below.

Docker

docker build -t activedirectory-mcp .

The image runs the HTTP server as a non-root user on port 8813. It exits immediately with instructions if no API key is configured.

With Compose, which mounts ./ad-config read-only and refuses to start without a key:

export AD_MCP_HTTP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
cp ad-config/config.example.json ad-config/ad-config.json     # then edit it as described above
export AD_BIND_DN='CN=service-account,OU=Service Accounts,DC=example,DC=com'
read -rs AD_PASSWORD && export AD_PASSWORD                     # not echoed; skip both with Key Vault
docker compose up -d
docker compose ps
curl -sf http://127.0.0.1:8813/health

Compose passes AD_BIND_DN and AD_PASSWORD from your shell (or a .env file next to docker-compose.yml) into the container. Without them, and without Key Vault, the server exits at startup with "No AD bind password available" and restart: unless-stopped keeps retrying, so check docker compose logs if /health does not answer. For Azure Key Vault, uncomment the AZURE_KEYVAULT_* lines in docker-compose.yml instead and leave AD_PASSWORD unset; the plaintext variable is visible in docker inspect, so prefer Key Vault. Do not bake secrets into the image or the config file. The HTTP address inside the container is fixed (0.0.0.0:8813); change the published port in ports, not an environment variable.

Verification note: docker build, the fail-fast start without a key, /health, the 401 without a key and acceptance of both key headers were exercised against a container without a reachable directory. docker compose up against a real domain controller was not verified here.

Connect an MCP client

Create the config file first (see Quickstart). The bind password must not be written into a file that is committed or shared. Complete examples are in examples/.

Claude Desktop (stdio)

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\; the Linux location is not covered by the official documentation):

{
    "mcpServers": {
        "ActiveDirectoryMCP": {
            "command": "uv",
            "args": ["--directory", "/absolute/path/to/ActiveDirectoryMCP", "run", "activedirectory-mcp"],
            "env": {
                "AD_MCP_CONFIG": "/absolute/path/to/ActiveDirectoryMCP/ad-config/ad-config.json",
                "AD_BIND_DN": "CN=service-account,OU=Service Accounts,DC=example,DC=com",
                "AD_PASSWORD": "REPLACE_WITH_BIND_PASSWORD"
            }
        }
    }
}

Claude Desktop does not document environment-variable interpolation, so the env block holds the value literally in a local file. Prefer Azure Key Vault (leave AD_PASSWORD out and configure key_vault) so no password is stored. If uv is not found, use its absolute path as command.

Claude Code

Stdio (the command after -- is the server; -e sets its environment, -s the scope):

claude mcp add activedirectory -e AD_MCP_CONFIG="$PWD/ad-config/ad-config.json" \
  -e AD_BIND_DN="$AD_BIND_DN" -e AD_PASSWORD="$AD_PASSWORD" \
  -- uv --directory "$PWD" run activedirectory-mcp

Streamable HTTP with the API key header:

claude mcp add --transport http activedirectory http://localhost:8813/activedirectory-mcp \
  --header "Authorization: Bearer $AD_MCP_HTTP_API_KEY"

claude mcp add stores the values you pass in your Claude Code configuration. To keep secrets out of it, commit a project-scoped .mcp.json instead, which expands ${VAR} in command, args, env, url and headers:

{
    "mcpServers": {
        "activedirectory-stdio": {
            "type": "stdio",
            "command": "uv",
            "args": ["--directory", "${CLAUDE_PROJECT_DIR:-.}", "run", "activedirectory-mcp"],
            "env": {
                "AD_MCP_CONFIG": "${CLAUDE_PROJECT_DIR:-.}/ad-config/ad-config.json",
                "AD_BIND_DN": "${AD_BIND_DN}",
                "AD_PASSWORD": "${AD_PASSWORD}"
            }
        },
        "activedirectory-http": {
            "type": "http",
            "url": "http://localhost:8813/activedirectory-mcp",
            "headers": {
                "Authorization": "Bearer ${AD_MCP_HTTP_API_KEY}"
            }
        }
    }
}

The claude mcp add flags above were confirmed with claude mcp add --help; the commands were not executed here because they change the operator's Claude Code configuration.

Cursor

Put this in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Cursor resolves ${env:NAME} in command, args, env, url and headers:

{
    "mcpServers": {
        "ActiveDirectoryMCP": {
            "command": "uv",
            "args": ["--directory", "/absolute/path/to/ActiveDirectoryMCP", "run", "activedirectory-mcp"],
            "env": {
                "AD_MCP_CONFIG": "/absolute/path/to/ActiveDirectoryMCP/ad-config/ad-config.json",
                "AD_BIND_DN": "${env:AD_BIND_DN}",
                "AD_PASSWORD": "${env:AD_PASSWORD}"
            }
        }
    }
}

For an HTTP server started as described above:

{
    "mcpServers": {
        "ActiveDirectoryMCP-HTTP": {
            "url": "http://localhost:8813/activedirectory-mcp",
            "headers": {
                "Authorization": "Bearer ${env:AD_MCP_HTTP_API_KEY}"
            }
        }
    }
}

Security configuration

Write access and the HTTP transport are locked down by default. Example (placeholder values only):

{
    "security": {
        "allow_writes": false,
        "allow_destructive": false,
        "max_list_results": 1000,
        "protect_privileged_targets": true,
        "audit_log_path": "/var/log/ad-mcp/audit.jsonl",
        "http_auth": {
            "required": true,
            "api_key_sha256": ["0000000000000000000000000000000000000000000000000000000000000000"]
        }
    }
}

• security.allow_writes enables create, modify, enable, disable, reset, move and membership tools;

security.allow_destructive additionally enables the delete tools and requires allow_writes. Refused calls return a structured error (write_blocked or destructive_blocked) naming the setting to change.

• security.max_list_results caps list and report tools (0 = unlimited); responses include

truncated and result_limit. The audit tools (get_inactive_users, get_password_policy_violations, get_stale_computers) scan the whole directory and cap only the findings they return.

• security.protect_privileged_targets (default true) makes add_group_member,

remove_group_member and reset_user_password refuse privileged groups and accounts (Domain/Enterprise/Schema Admins, Administrators, operator groups, krbtgt, Administrator, anything with adminCount=1). Set it to false only if you accept that anyone with allow_writes can change them.

• security.audit_log_path (default unset) writes one JSON line per write or destructive tool call

(timestamp, tool, risk, target, outcome, redacted arguments; no passwords) to a file opened in append mode with mode 0600 (the service user can still truncate or delete it; use chattr +a or ship the lines elsewhere if you need tamper resistance). The server refuses to start if the path cannot be opened and logs a warning when allow_writes is true without a path. Destructive calls also write an intent record first; HTTP calls add an actor.

• security.audit_fail_closed (default false, needs audit_log_path) refuses write and destructive

calls when the audit record cannot be written, instead of running them unaudited.

• security.http_auth.required (default true) keeps the API key mandatory. Setting it to false

disables HTTP authentication entirely; this is unsafe and only suitable for an isolated test.

• security.require_secure_connection (default true) rejects non-LDAPS connection settings at

startup. Password tools (create_user with a password, reset_user_password, reset_computer_password) additionally require an LDAPS or StartTLS connection and are refused otherwise.

• reset_user_password and reset_computer_password return the new password in the response;

treat it as sensitive and do not log it client-side. reset_computer_password breaks the machine's secure channel, so the machine must be rejoined or re-synced.

• modify_* tools accept only allow-listed attributes (security-sensitive ones such as

userAccountControl, servicePrincipalName and gPLink are always rejected). Every DN a tool receives must lie inside the configured base_dn.

Generate and hash an HTTP API key:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"      # the key
python3 -c "import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest())" '<key>'

Provide the key through AD_MCP_HTTP_API_KEY, or only its digest through AD_MCP_HTTP_API_KEY_SHA256 (comma-separated for several keys) or security.http_auth.api_key_sha256. Plaintext keys are never read from the config file. Clients send Authorization: Bearer <key> or X-API-Key: <key>.

Tools

45 tools. The risk column is what security.allow_writes and security.allow_destructive enforce: read tools always run, write tools need allow_writes, destructive tools need both settings.

Users

Groups

Computers

Organizational units

Security and audit

Diagnostics

Some LLM clients degrade when many tools are in context; that is a client limit, not a server one.

Multiple domains

One server instance can serve several domains. Point AD_MCP_CONFIG at a file with a domains object instead of a single-domain config (see ad-config/multi.example.json):

• Each value under domains is either a path to an existing single-domain config file (relative

paths are resolved against the multi-domain file) or the same config inline.

• default_domain names the domain used when a call does not pass one (default: the first).
• logging and http_auth are set once at the top level and apply to the whole instance.
• Every other setting stays per domain, including security: write and destructive tools can be

allowed in one domain and refused in another, and audit records carry the domain name.

With more than one domain, every tool takes an optional domain argument and a read-only list_domains tool reports the configured domains, the default and their write settings. The number of tools does not grow with the number of domains. With one domain the tool surface is unchanged.

The process-wide credential variables (AD_BIND_DN, AD_PASSWORD and the AZURE_KEYVAULT_* variables) would apply to every domain, so startup refuses them when several domains are configured. Give each domain its own password placeholder (for example "password": "${CORP_AD_PASSWORD}") or its own key_vault section.

For an LDAP proxy that does not publish the directory schema, set "skip_schema": true in that domain's active_directory section (the AD_MCP_SKIP_SCHEMA environment variable still sets the default for every domain).

Configuration reference

Credentials

The service account name and password are resolved in this order: Azure Key Vault, then the AD_BIND_DN and AD_PASSWORD environment variables, then values in the config file (a plaintext password there logs a deprecation warning). Startup fails with a clear error if no password can be resolved.

Azure Key Vault is an optional extra (uv sync --locked --extra azure):

{
    "key_vault": {
        "vault_url": "https://your-keyvault-name.vault.azure.net/",
        "username_secret_name": "ad-bind-username",
        "password_secret_name": "ad-bind-password"
    }
}

The same can be set with AZURE_KEYVAULT_URL, AZURE_KEYVAULT_SECRET_USERNAME and AZURE_KEYVAULT_SECRET_PASSWORD (see .env.example). Authentication uses DefaultAzureCredential: a managed identity (recommended in Azure), the service principal variables AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, or az login for local use. Grant the identity permission to read secrets only. username_secret_name is optional; without it the bind_dn from the config file is used.

Default organizational units

organizational_units sets where create_computer and create_group place objects when no ou is passed. It is optional: missing entries default to the built-in containers under base_dn (CN=Computers,<base_dn> for computers, CN=Users,<base_dn> otherwise).

TLS

{
    "security": {
        "enable_tls": true,
        "validate_certificate": true,
        "ca_cert_file": "/path/to/ca-certificate.pem",
        "require_secure_connection": true
    }
}

Keep certificate validation on. Use ca_cert_file for an internal CA. get_tls_posture reports the effective settings of a running server.

Performance

{
    "performance": {
        "max_retries": 3,
        "retry_delay": 1.0,
        "page_size": 1000
    }
}

connection_pool_size is deprecated and ignored; it is accepted only so older configuration files keep loading.

Service account

Create a dedicated account with the minimum rights for the tools you enable. Read-only use needs read access to the relevant subtrees only. Keep allow_writes off unless you need it, and delegate write permissions on specific OUs rather than using a domain admin.

Testing

Details are in TESTING_GUIDE.md.

uv run pytest -q                    # unit and end-to-end tests with a mocked directory
scripts/run_tests_with_ldap.sh      # live tests against the OpenLDAP lab (needs Docker)

Unit tests mock ldap3 and never connect to a directory; integration tests are deselected by default. The lab (docker-compose-openldap.yml) is OpenLDAP, not Active Directory: it does not enforce userAccountControl, unicodePwd TLS rules, lastLogon replication or AD ACLs. It needs a throwaway LAB_LDAP_PASSWORD, which the script generates per run. The lab client configuration is ad-config/openldap-lab.example.json; an example Cursor entry is in examples/cursor_openldap_config.json.

Manual smoke scripts live in tests/manual/ (http_server_smoke.py needs a running HTTP server; real_ad_smoke.py needs AD_MCP_CONFIG pointing at a real directory).

Troubleshooting

• HTTP server exits at start with "requires an API key": set AD_MCP_HTTP_API_KEY (or the SHA-256

digest variable) as shown above.

• Secure connection required but server URL is not ldaps://: use an ldaps:// server URL or, for

a lab only, set security.require_secure_connection to false.

• invalid CA public key file: security.ca_cert_file points at a missing file; fix or remove it.
• Failed to retrieve a secret from Key Vault: configure the vault correctly or delete the

key_vault section when using AD_BIND_DN and AD_PASSWORD.

• write_blocked or destructive_blocked in a tool response: the server is read-only by default;

set security.allow_writes (and security.allow_destructive for deletes) deliberately.

• Errors mentioning a DN outside the base DN: the DN passed to a tool must be inside

active_directory.base_dn.

• LDAPS certificate errors: check the chain with `openssl s_client -connect dc.example.com:636

-showcerts and point security.ca_cert_file` at your CA.

• Connectivity: `ldapsearch -H ldaps://dc.example.com -D "<bind DN>" -W -b "<base DN>"

"(objectClass=domain)", then the test_connection and get_tls_posture` tools.

• Port 8813 busy: pass --port or set HTTP_PORT for the launcher scripts.
• Logs: docker logs -f activedirectory-mcp for the container; otherwise the file set in

logging.file.

Project structure

src/active_directory_mcp/   server code (registry, policy, audit, auth, tools/, config/, core/)
tests/                      unit, e2e, integration, golden and manual tests
ad-config/                  example configurations (your ad-config.json stays untracked)
examples/                   MCP client configuration examples
ldap-init/                  OpenLDAP lab seed data
scripts/                    helper scripts
Dockerfile, docker-compose.yml, docker-compose-openldap.yml
pyproject.toml, uv.lock

Tools are declared once in src/active_directory_mcp/registry.py and served by both transports.

Contributing, security and license

• CONTRIBUTING.md explains how to propose changes.
• SECURITY.md explains how to report a vulnerability.
• CHANGELOG.md lists user-visible changes, including breaking ones.
• Licensed under the MIT License, see LICENSE.

Related projects

• ProxmoxMCP-Extended, the project this one was

inspired by

• Model Context Protocol
• FastMCP