Skip to main content
Glama
Sign In
deenesjakoruzh
Skills MCP AD

Skills MCP AD

by DevSkillsIT
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

关于

Active Directory MCP 是一个开源的 Model Context Protocol 服务器，让 AI 助手（Claude、Gemini CLI、通过 API 的 ChatGPT 等）能够安全地管理 Active Directory 环境。

主要特性

  • 47 个工具，涵盖用户、组、计算机、OU、安全、审计以及 15 个 MSP 提示词剧本。

  • 三种传输方式：stdio（server.py）、通过 FastMCP 的 Streamable HTTP（server_http.py）以及通过 FastAPI 的 Streamable HTTP（server_fastapi.py）。

  • 天然多租户：每个实例通过 AD_MCP_CONFIG 绑定到自己的 AD；同一套代码库可从一台主机服务无限数量的租户。

  • 写操作护栏：每个变更工具在触碰 AD 之前，都需要租户级别的客户端确认字符串或自动化 Bearer 令牌。

  • 每次操作均有审计日志：每次调用都会记录操作名称、目标、模式（CONFIRMED / AUTOMATION / NO_CONFIRMATION_REQUIRED）和结果。

命名约定

所有 MCP 工具名称使用 ad_* 前缀并带有描述性后缀——例如 ad_list_users_with_filters、ad_create_user_account、ad_disable_computer_account_trust。这可以避免当此 MCP 与连接到同一 AI 客户端的其他服务器（GLPI、Hudu 等）并行运行时发生名称冲突。

Related MCP server: Shell MCP

多租户架构

此 MCP 设计为每个租户运行一个进程，所有进程共享同一套代码：

.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

每个 start.sh 导出指向该租户配置的 AD_MCP_CONFIG，并在专用端口上运行 python -m active_directory_mcp.server_http。只需更新一次共享的 .base-code/，重启所有租户——同一套代码，隔离的状态。

快速开始

前置条件

  • Python 3.11+

  • 主机可访问 LDAP/LDAPS

  • 一个具有你计划暴露的操作所需权限的 AD 服务账户

1. 安装

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. 配置

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

示例文件是 git 中保留的唯一模板。任何真实的 ad-config.json 都会被 .gitignore 阻止（ad-config/*.json + !ad-config/*.example.json）。

3. 运行

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. 从 Claude Code 连接

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

5. 从 Gemini CLI 连接

~/.gemini/settings.json：

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

工具

所有工具均使用 ad_* 前缀。标记为写入的工具需要确认字符串或自动化 Bearer 令牌。

租户识别（3）

工具

操作

ad_get_client_tenant_info

返回此实例的租户信息（首先调用）

ad_list_configured_clients

列出客户端注册表中注册的所有客户端

ad_check_client_configuration

检查给定客户端 slug 是否已配置 AD

用户管理（9）

工具

写入

操作

ad_list_users_with_filters

—

列出用户（可选按 OU/条件过滤）

ad_get_user_details_by_username

—

按 sAMAccountName 获取用户属性

ad_get_user_group_memberships

—

列出用户所属的组

ad_create_user_account

是

创建新用户

ad_modify_user_attributes

是

修改用户属性

ad_delete_user_account_permanently

是

删除用户

ad_enable_user_account_access

是

启用用户账户

ad_disable_user_account_access

是

禁用用户账户

ad_reset_user_password_forced

是

重置密码（强制下次登录时更改）

组管理（8）

工具

写入

操作

ad_list_groups_with_filters

—

列出组

ad_get_group_details_by_name

—

获取组属性

ad_get_group_members_recursive

—

列出成员，可选递归

ad_create_group_security_or_distribution

是

创建安全组或通讯组

ad_modify_group_attributes

是

修改组属性

ad_delete_group_permanently

是

删除组

ad_add_member_to_group

是

添加成员

ad_remove_member_from_group

是

移除成员

计算机管理（8）

工具

写入

操作

ad_list_computers_with_filters

—

列出计算机

ad_get_computer_details_by_name

—

获取计算机属性

ad_get_inactive_computers_by_days

—

列出空闲 N+ 天的计算机

ad_create_computer_account

是

创建计算机对象

ad_modify_computer_attributes

是

修改计算机属性

ad_delete_computer_account_permanently

是

删除计算机对象

ad_enable_computer_account_trust

是

启用计算机账户

ad_disable_computer_account_trust

是

禁用计算机账户

ad_reset_computer_password_trust

是

重置计算机安全通道密码

组织单位管理（7）

工具

写入

操作

ad_list_organizational_units_hierarchy

—

列出 OU（可选递归）

ad_get_organizational_unit_details

—

获取 OU 属性

ad_get_organizational_unit_objects

—

列出 OU 内的对象

ad_create_organizational_unit

是

创建 OU

ad_modify_organizational_unit_attributes

是

修改 OU

ad_delete_organizational_unit_forced

是

删除 OU（force=true 可删除非空 OU）

ad_move_organizational_unit_parent

是

将 OU 移动到新的父级

安全与审计（6）

工具

操作

ad_get_domain_security_policy_info

域信息 + 密码/锁定策略

ad_get_privileged_security_groups

列出特权组（Domain Admins、Enterprise Admins 等）

ad_get_user_effective_permissions

显示用户的有效权限

ad_get_inactive_users_by_days

超过 N 天未登录的用户

ad_get_password_policy_violations

违反密码策略的账户

ad_audit_administrative_accounts

审计特权账户卫生状况

MSP 提示词（2 个工具 + 15 个提示词）

工具

操作

ad_list_msp_prompts

列出 15 个专业 MSP 剧本（经理和分析师）

ad_execute_msp_prompt

使用参数执行指定的剧本

有关完整提示词目录（安全审计、入职、离职、密码重置剧本等），请参阅 PROMPTS.md。

系统（4）

工具

操作

ad_test_ldap_connection_status

LDAP 连接探测

ad_health_check_mcp_server

完整健康检查（服务器 + LDAP 搜索测试 + 统计）

ad_get_mcp_schema_tools_info

所有已注册工具的自描述模式

配置

运行时配置文件路径通过 AD_MCP_CONFIG 环境变量提供。模式见 ad-config/ad-config.example.json。

关键字段

字段

必填

描述

active_directory.server

是

主 LDAP URL，例如 ldaps://dc.example.com:636

active_directory.server_pool

否

用于故障转移的附加 LDAP URL

active_directory.bind_dn

是

服务账户的完整 DN

active_directory.password

是

服务账户密码（将文件权限保持为 chmod 600）

active_directory.base_dn

是

基础 DN，例如 DC=example,DC=com

organizational_units.*

是

用户/组/计算机/服务账户的默认 OU

security.enable_tls

否

强制使用 StartTLS / LDAPS

security.validate_certificate

否

根据 ca_cert_file 验证服务器证书

security.require_secure_connection

否

拒绝通过明文进行绑定

automation.token

否

用于无人值守写入操作的 Bearer 令牌

client.slug

否

由 ad_get_client_tenant_info 报告的租户标识符

服务账户权限

为绑定账户授予您打算公开的操作所需的最低委派权限：

  • 只读部署：在域根上授予“读取所有属性”+“列出内容”即可。

  • 用户/组写入：在目标 OU 上委派“创建/删除对象”+“写入所有属性”。

  • 密码重置：在目标 OU 上委派“重置密码”扩展权限。

  • 计算机加入/退出域：在计算机 OU 上委派“创建/删除计算机对象”。

始终使用专用服务账户，在生产环境中使用 LDAPS，并定期轮换密码。

安全

写入保护模型

每个变更工具（ad_create_*、ad_modify_*、ad_delete_*、ad_enable_*、ad_disable_*、ad_reset_*、ad_add_*、ad_remove_*、ad_move_*）在到达 LDAP 之前都会调用 check_write_permission()。只要满足以下任一条件，它就会接受写入：

  1. automation_token 与配置中的 automation.token 匹配——适用于 CI / 计划任务。

  2. client_confirmation 与租户 slug 匹配——AI 助手必须首先调用 ad_get_client_tenant_info，将 slug 读回给用户，并传递该确切字符串。

  3. 租户设置了 require_confirmation_for_writes: false（显式选择退出，不推荐）。

如果以上条件均不满足，调用将以 permitted: false 消息短路返回，并且永远不会尝试 LDAP 写入。

审计日志

所有操作都会写入一条结构化日志行，包括：时间戳、工具名称、目标、确认模式（AUTOMATION / CONFIRMED / WRONG_CONFIRMATION / NO_CONFIRMATION_REQUIRED）以及成功/失败状态。日志写入 logging.file 指向的位置。

机密信息卫生

  • 真实的 ad-config.json 文件已被 git 忽略。仅跟踪 *.example.json。

  • 切勿将包含真实 password 或 automation.token 的配置粘贴到会被第三方记录或转录的聊天中。

  • 每次重新生成 automation.token 时都要轮换它；将其视为特权凭据。

测试

# Unit + integration tests
pytest tests/ -v

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

# Lint
ruff check .

捆绑的 docker-compose-ad.yml 会在 192.168.1.100 启动一个 Samba AD 容器，外加一个 MCP 容器，以便集成测试可以针对真实的 LDAP 后端运行，而不会触及生产环境。

故障排查

症状

可能原因

修复

LDAP bind failed

bind_dn / password 错误

使用 ldapsearch -H <server> -D '<bind_dn>' -W 进行验证

Insufficient permissions

服务账户缺少委派权限

在目标 OU 上重新委派

Certificate verification failed

自签名证书未受信任

设置 ca_cert_file 或 validate_certificate: false（仅限测试）

每次写入都返回 permitted: false

缺少确认/令牌

首先调用 ad_get_client_tenant_info，或传递 automation_token

Health degraded

套接字已打开但 LDAP 搜索失败

检查服务账户锁定 / 复制 / 网络 ACL

贡献

  1. Fork 该仓库。

  2. 创建功能分支：git checkout -b feat/your-feature。

  3. 运行测试：pytest。

  4. 提交 PR，附上清晰的描述和相关 issue 的链接。

提交遵循 Conventional Commits。

许可证

MIT — 参见 LICENSE。

致谢

支持

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • ActiveDirectoryMCP

    alpadalar
    A
    license
    B
    quality
    B
    maintenance
    A comprehensive MCP server for managing Active Directory environments through LDAP, enabling user, group, computer, and OU management, as well as security auditing and policy compliance checks.
    45
    52
    MIT

  • Shell MCP

    luciVuc
    A
    license
    A
    quality
    D
    maintenance
    A production-ready MCP server that enables AI assistants to execute shell commands, manage files, monitor system resources, and automate complex workflows with advanced features like stock tracking and web automation.
    7
    17 npm
    MIT

  • LegacyMCP

    Marco-Lelli
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enables AI-powered assessment of Active Directory on-premises environments by exposing AD data as queryable tools for LLMs like Claude.
    MIT

  • windows-admin-mcp

    devladpopov
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to manage, monitor, and diagnose Windows systems through 42 tools across 8 modules, including services, event viewer, task scheduler, processes, network, diagnostics, observability, and safety features.
    18 npm
    9
    MIT