Skills MCP AD

Acerca de

Active Directory MCP es un servidor de Model Context Protocol de código abierto que permite a los asistentes de IA (Claude, Gemini CLI, ChatGPT vía API, etc.) gestionar entornos de Active Directory de forma segura.

Características principales

• 47 herramientas que cubren usuarios, grupos, equipos, UO, seguridad, auditoría y 15 playbooks de prompts para MSP.

• Tres transportes: stdio (server.py), HTTP Streamable vía FastMCP (server_http.py) y HTTP Streamable vía FastAPI (server_fastapi.py).

• Multiinquilino por diseño: cada instancia se vincula a su propio AD mediante AD_MCP_CONFIG; el mismo código base puede atender a un número ilimitado de inquilinos desde un único host.

• Protecciones para operaciones de escritura: cada herramienta de mutación requiere una cadena de confirmación del cliente por inquilino o un token Bearer de automatización antes de tocar AD.

• Registro de auditoría en cada operación: cada llamada registra el nombre de la operación, el objetivo, el modo (CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED) y el resultado.

Convención de nombres

Todos los nombres de herramientas MCP usan el prefijo ad_* con un sufijo descriptivo — p. ej. ad_list_users_with_filters, ad_create_user_account, ad_disable_computer_account_trust. Esto evita colisiones cuando este MCP se ejecuta junto a otros servidores (GLPI, Hudu, etc.) conectados al mismo cliente de IA.

Related MCP server: Shell MCP

Arquitectura multiinquilino

Este MCP está diseñado para ejecutarse como un proceso por inquilino, compartiendo todos el mismo código:

.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

Cada start.sh exporta AD_MCP_CONFIG apuntando a la configuración de ese inquilino y ejecuta python -m active_directory_mcp.server_http en un puerto dedicado. Actualiza el .base-code/ compartido una vez, reinicia todos los inquilinos — mismo código, estado aislado.

Inicio rápido

Requisitos previos

• Python 3.11+

• LDAP/LDAPS accesible desde el host

• Una cuenta de servicio de AD con los permisos requeridos por las operaciones que planeas exponer

1. Instalación

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. Configuración

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

El archivo de ejemplo es la única plantilla mantenida en git. Cualquier ad-config.json real está bloqueado por .gitignore (ad-config/*.json + !ad-config/*.example.json).

3. Ejecución

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. Conexión desde Claude Code

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

5. Conexión desde Gemini CLI

~/.gemini/settings.json:

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

Herramientas

Todas las herramientas usan el prefijo ad_*. Las herramientas marcadas como Escritura requieren una cadena de confirmación O un token Bearer de automatización.

Identificación de inquilino (3)

Gestión de usuarios (9)

Gestión de grupos (8)

Gestión de equipos (8)

Gestión de unidades organizativas (7)

Seguridad y auditoría (6)

Prompts MSP (2 herramientas + 15 prompts)

Consulta PROMPTS.md para el catálogo completo de prompts (auditoría de seguridad, incorporación, baja, playbook de restablecimiento de contraseña, etc.).

Sistema (4)

Configuración

La ruta del archivo de configuración en tiempo de ejecución se proporciona mediante la variable de entorno AD_MCP_CONFIG. Esquema en ad-config/ad-config.example.json.

Campos clave

Permisos de la cuenta de servicio

Conceda a la cuenta de enlace los derechos delegados mínimos requeridos por las operaciones que desee exponer:

• Implementaciones de solo lectura: "Leer todas las propiedades" + "Listar contenido" en la raíz del dominio es suficiente.

• Escritura de usuarios/grupos: delegue "Crear/Eliminar objetos" + "Escribir todas las propiedades" en las UO objetivo.

• Restablecimiento de contraseña: delegue el derecho extendido "Restablecer contraseña" en las UO objetivo.

• Unión/salida de equipos: delegue "Crear/Eliminar objetos de equipo" en la UO de equipos.

Utilice siempre una cuenta de servicio dedicada, LDAPS en producción y rote la contraseña regularmente.

Seguridad

Modelo de protección de escritura

Cada herramienta de mutación (ad_create_*, ad_modify_*, ad_delete_*, ad_enable_*, ad_disable_*, ad_reset_*, ad_add_*, ad_remove_*, ad_move_*) llama a check_write_permission() antes de llegar a LDAP. Acepta la escritura si una de:

1. automation_token coincide con automation.token en la configuración — destinado a CI / trabajos programados.

2. client_confirmation coincide con el slug del inquilino — el asistente de IA debe llamar primero a ad_get_client_tenant_info, leer el slug de vuelta al usuario y pasar esa cadena exacta.

3. El inquilino tiene require_confirmation_for_writes: false (opt-out explícito, no recomendado).

Si ninguna de las anteriores se cumple, la llamada se cortocircuita con un mensaje permitted: false y la escritura LDAP nunca se intenta.

Registro de auditoría

Todas las operaciones escriben una línea de registro estructurada que incluye: marca de tiempo, nombre de la herramienta, objetivo, modo de confirmación (AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED) y éxito/fracaso. Los registros van donde apunte logging.file.

Higiene de secretos

• Los archivos ad-config.json reales están ignorados por git. Solo se rastrea *.example.json.

• Nunca pegue una configuración que contenga una password o automation.token reales en un chat que sea registrado o transcrito por un tercero.

• Rote automation.token cada vez que lo regenere; trátelo como una credencial privilegiada.

Pruebas

# Unit + integration tests
pytest tests/ -v

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

# Lint
ruff check .

Un docker-compose-ad.yml incluido levanta un contenedor Samba AD en 192.168.1.100 más un contenedor MCP para que las pruebas de integración puedan ejecutarse contra un backend LDAP real sin tocar producción.

Solución de problemas

Contribuciones

1. Haga un fork del repositorio.

2. Cree una rama de características: git checkout -b feat/your-feature.

3. Ejecute las pruebas: pytest.

4. Abra un PR con una descripción clara y un enlace al problema relevante.

Los commits siguen Conventional Commits.

Licencia

MIT — consulte LICENSE.

Agradecimientos

• Basado en el proyecto upstream alpadalar/ActiveDirectoryMCP de Alperen Adalar.

• Construido sobre mcp, fastmcp, ldap3 y FastAPI.

Soporte

• Informes de errores: GitHub Issues

• Discusiones: GitHub Discussions