Skills MCP AD

About

Active Directory MCP is an open-source Model Context Protocol server that lets AI assistants (Claude, Gemini CLI, ChatGPT via API, etc.) safely manage Active Directory environments.

Key features

• 45 tools covering users, groups, computers, OUs, security, and audit, plus 15 MSP prompt playbooks served through the MCP prompts protocol.

• Two transports: stdio (server.py) for direct CLI/desktop clients, and Streamable HTTP via FastAPI (server_fastapi.py) for everything else. An earlier FastMCP-based HTTP transport (server_http.py) has been removed.

• Two deployment modes: single (default) binds one process to one AD via AD_MCP_CONFIG — run one process per tenant to serve several; multi binds one process to N ADs via AD_MCP_SERVERS, adding a required/optional ad_server parameter to every directory-bound tool. See Multi-tenant architecture.

• Write-operation guard rails: every mutating tool requires either a per-tenant client confirmation string or an automation Bearer token before touching AD.

• Audit log on every operation: each call records operation name, target, mode (CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED), and outcome.

Naming convention

All MCP tool names use the ad_* prefix with a descriptive suffix — e.g. ad_list_users_with_filters, ad_create_user_account, ad_disable_computer_account_trust. This avoids collisions when this MCP runs alongside other servers (GLPI, Hudu, etc.) connected to the same AI client.

Related MCP server: Shell MCP

Multi-tenant architecture

There are two ways to serve more than one AD with this codebase. Both read the same active_directory / organizational_units / security / client schema (see Configuration); pick one per deployment, not both.

Mode 1 — one process per tenant (AD_MCP_MODE=single, the default)

.base-code/                    <- this repository (shared source of truth)
  src/active_directory_mcp/
  ad-config/
    ad-config.example.json     <- template only (real configs are .gitignored)

<deployment>/                  <- one directory per tenant, OUTSIDE this repo
  tenant-a/
    ad-config/ad-config.json   <- real credentials (NEVER committed)
    start.sh                   <- exports AD_MCP_CONFIG and launches the server
  tenant-b/
    ad-config/ad-config.json
    start.sh

Each start.sh exports AD_MCP_CONFIG pointing at that tenant's config and runs python -m active_directory_mcp.server_fastapi on a dedicated port. Update the shared .base-code/ once, restart every tenant process — same code, isolated state. Tools take no ad_server parameter in this mode; this is the original, unchanged behavior.

Mode 2 — one process serving several ADs (AD_MCP_MODE=multi)

A single server_fastapi.py process can instead serve N directories, selected via AD_MCP_SERVERS pointing at an ad-servers.json (schema: ad-config/ad-servers.example.json — each entry is an ad-config.json block plus label/aliases/enabled). Every directory-bound tool then gains an ad_server parameter:

• Write tools: ad_server is required and must name exactly one directory — there is no "all".

• Read tools: ad_server is optional; omitted (or all/todos/*) runs the query against every configured directory and the response reports where each result was found.

• Catalog tools: ad_list_configured_clients and ad_check_client_configuration are replaced by ad_list_ad_servers and ad_check_ad_server_configured, which resolve a name, alias, domain or client name to the exact value to pass as ad_server. ad_get_client_tenant_info still exists but, like every other directory-bound tool, now takes ad_server (optional) instead of describing "the" tenant.

ad_server matching ignores case, accents and surrounding whitespace; a name that matches more than one directory is refused with the list of candidates rather than guessed. Write confirmation (client_confirmation, below) is validated against the same directory named by ad_server.

export AD_MCP_MODE=multi
export AD_MCP_SERVERS=/etc/ad-mcp/ad-servers.json
python -m active_directory_mcp.server_fastapi --host 0.0.0.0 --port 8820

The stdio transport (server.py) only supports single mode.

Quick Start

Prerequisites

• Python 3.11+

• LDAP/LDAPS reachable from the host

• An AD service account with the permissions required by the operations you plan to expose

1. Install

git clone https://github.com/DevSkillsIT/Skills-MCP-Active-Directory.git
cd Skills-MCP-Active-Directory

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows

pip install -e .                   # installs from pyproject.toml

2. Configure

mkdir -p /etc/ad-mcp
cp ad-config/ad-config.example.json /etc/ad-mcp/ad-config.json
$EDITOR /etc/ad-mcp/ad-config.json   # set server, bind_dn, password, base_dn, OUs
chmod 600 /etc/ad-mcp/ad-config.json

The example file is the only template kept in git. Any real ad-config.json is blocked by .gitignore (ad-config/*.json + !ad-config/*.example.json).

3. Run

export AD_MCP_CONFIG=/etc/ad-mcp/ad-config.json

# stdio transport (for direct Claude Desktop / mcp-cli use):
python -m active_directory_mcp.server

# HTTP transport (for Claude Code, Gemini CLI, n8n, etc.):
python -m active_directory_mcp.server_fastapi --host 0.0.0.0 --port 8820
# MCP endpoint: http://localhost:8820/mcp   Health (no auth): http://localhost:8820/health

Set AD_MCP_API_TOKEN in the environment to require a Bearer token on the HTTP transport; without it the server accepts unauthenticated requests (development only — always set it in production). See HTTP_MCP_GUIDE.md for the full transport reference, including the multi mode.

4. Connect from Claude Code

claude mcp add --transport http ad http://localhost:8820/mcp \
  --headers "Authorization: Bearer YOUR_AUTOMATION_TOKEN"

5. Connect from Gemini CLI

~/.gemini/settings.json:

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

Tools

All tools use the ad_* prefix. Tools marked as Write require a confirmation string OR an automation Bearer token. The tables below describe single mode (the default, 45 tools). In multi mode every tool listed here also gets an ad_server parameter, and ad_list_configured_clients / ad_check_client_configuration below are replaced by ad_list_ad_servers / ad_check_ad_server_configured — see Multi-tenant architecture.

Tenant identification (3)

User management (9)

Group management (8)

Computer management (9)

Organizational Unit management (7)

Security & audit (6)

MSP prompts (15)

The 15 professional MSP playbooks (7 manager + 8 analyst) are not tools — they are served through the standard MCP prompts protocol, prompts/list and prompts/get, over the FastAPI HTTP transport only (the stdio transport does not expose them). See PROMPTS.md for the full catalog and usage.

System (3)

Configuration

The runtime configuration file path is provided via the AD_MCP_CONFIG environment variable. Schema in ad-config/ad-config.example.json.

Key fields

Service account permissions

Grant the bind account the minimum delegated rights required by the operations you intend to expose:

• Read-only deployments: "Read all properties" + "List contents" on the domain root is enough.

• User/group write: delegate "Create/Delete objects" + "Write all properties" on the target OUs.

• Password reset: delegate the "Reset password" extended right on the target OUs.

• Computer join/leave: delegate "Create/Delete computer objects" on the computers OU.

Always use a dedicated service account, LDAPS in production, and rotate the password regularly.

Security

Write protection model

Every mutating tool (ad_create_*, ad_modify_*, ad_delete_*, ad_enable_*, ad_disable_*, ad_reset_*, ad_add_*, ad_remove_*, ad_move_*) calls check_write_permission() before reaching LDAP. It accepts the write if one of:

1. automation_token matches automation.token in the config — intended for CI / scheduled jobs.

2. client_confirmation matches the tenant slug — the AI assistant must call ad_get_client_tenant_info first, read the slug back to the user, and pass that exact string.

3. The tenant has require_confirmation_for_writes: false (explicit opt-out, not recommended).

If none of the above is satisfied, the call short-circuits with a permitted: false message and the LDAP write is never attempted.

Audit logging

All operations write a structured log line including: timestamp, tool name, target, confirmation mode (AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED), and success/failure. Logs go wherever logging.file points.

Secrets hygiene

• Real ad-config.json files are git-ignored. Only *.example.json is tracked.

• Never paste a config containing a real password or automation.token into a chat that's logged or transcribed by a third party.

• Rotate automation.token whenever you regenerate it; treat it as a privileged credential.

Testing

# Unit + integration tests
pytest tests/ -v

# Coverage
pytest --cov=src/active_directory_mcp --cov-report=term-missing

# Lint
ruff check .

A bundled docker-compose-ad.yml spins up a Samba AD container at 192.168.1.100 plus an MCP container so the integration tests can run against a real LDAP backend without touching production.

Troubleshooting

Contributing

1. Fork the repo.

2. Create a feature branch: git checkout -b feat/your-feature.

3. Run tests: pytest.

4. Open a PR with a clear description and a link to the relevant issue.

Commits follow Conventional Commits.

License

MIT — see LICENSE.

Acknowledgments

• Based on the upstream alpadalar/ActiveDirectoryMCP project by Alperen Adalar.

• Built on top of mcp, fastmcp, ldap3, and FastAPI.

Support

• Bug reports: GitHub Issues

• Discussions: GitHub Discussions