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

• 47 tools covering users, groups, computers, OUs, security, audit, and 15 MSP prompt playbooks.

• Three transports: stdio (server.py), Streamable HTTP via FastMCP (server_http.py), and Streamable HTTP via FastAPI (server_fastapi.py).

• Multi-tenant by design: each instance binds to its own AD via AD_MCP_CONFIG; the same codebase can serve unlimited tenants from one host.

• 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: ActiveDirectoryMCP

Multi-tenant architecture

This MCP is designed to run as one process per tenant, all sharing the same code:

.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_http on a dedicated port. Update the shared .base-code/ once, restart all tenants — same code, isolated state.

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-AD.git
cd Skills-MCP-AD

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_http --host 0.0.0.0 --port 8813 --path /activedirectory-mcp

4. Connect from Claude Code

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

5. Connect from Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "ad": {
      "httpUrl": "http://localhost:8813/activedirectory-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.

Tenant identification (3)

User management (9)

Group management (8)

Computer management (8)

Organizational Unit management (7)

Security & audit (6)

MSP prompts (2 tools + 15 prompts)

See PROMPTS.md for the full prompt catalog (security audit, onboarding, offboarding, password reset playbook, etc.).

System (4)

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