Ad MCP Server

Active Directory MCP服务器

用于管理Microsoft Active Directory的模型上下文协议（MCP）服务器。此服务器使Claude和其他MCP客户端能够与Active Directory交互，以执行用户管理、组操作和组织单位管理。

特性

• 用户管理：创建、修改、启用/禁用和删除用户帐户
• 密码操作：通过复杂性验证重置密码
• 用户搜索：按用户名、电子邮件或其他属性查询用户
• LDAPS支持：使用SSL/TLS保护LDAP连接
• 输入验证：全面验证以防止LDAP注入
• 审计日志：跟踪所有AD修改以符合要求

先决条件

• Python 3.10或更高版本
• 访问Active Directory环境
• 具有适当AD权限的服务帐户
• 在域控制器上配置LDAPS（推荐）

安装

1. 克隆存储库:

   cd D:\repo1

1. 创建虚拟环境:

   python -m venv venv

   # On Windows:
   venv\Scripts\activate

   # On Linux/Mac:
   source venv/bin/activate

1. 安装依赖项:

   pip install -e .

   # Or with uv (faster):
   uv pip install -e .

1. 安装开发依赖项 （可选）：

   pip install -e ".[dev]"

配置

1. 复制环境模板:

   copy .env.example .env

1. 编辑 .env 包含您的Active Directory详细信息:

   # Required settings
   AD_SERVER=dc01.example.com
   AD_PORT=636
   AD_USE_SSL=true
   AD_DOMAIN=EXAMPLE
   AD_BASE_DN=DC=example,DC=com

   # Service account credentials
   AD_BIND_DN=CN=MCP Service Account,OU=Service Accounts,DC=example,DC=com
   AD_BIND_PASSWORD=your_secure_password_here

   # Optional: Windows Integrated Authentication
   AD_USE_INTEGRATED_AUTH=false

   # Security settings
   AD_VERIFY_CERT=true
   AD_CERT_PATH=/path/to/ca-cert.pem

服务帐户权限

服务帐户需要以下Active Directory权限：

• 用户管理：在目标OU中创建、修改、删除用户对象
• 密码重置：重置密码权限
• 读取访问：读取所有用户属性
• 组管理：修改组成员资格（可选）

用法

运行服务器

单独模式

python -m src.main

配备MCP检查员（用于测试）

npx @modelcontextprotocol/inspector python -m src.main

Claude桌面集成

将此配置添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "active-directory": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "D:\\repo1"
    }
  }
}

注意：确保 .env 文件在项目目录中配置正确。

可用工具

create_user

在Active Directory中创建新用户。

参数:

• username （必填）：sAMAccountName，最多20个字符
• first_name （必填）：名字
• last_name （必填）：姓氏
• ou_path （必填）：OU的完整DN（例如。， OU=Users,DC=example,DC=com)
• password （必填）：初始密码（最少12个字符，需要复杂性）
• email （可选）：电子邮件地址
• upn （可选）：用户主体名称
• enabled （可选）：启用帐户（默认值：true）
• title （可选）：职位名称
• department （可选）：部门

示例:

Create a new user with username "jdoe", first name "John", last name "Doe"
in OU=Users,DC=example,DC=com with password "SecurePass123!"

get_user

从Active Directory获取用户信息。

参数 （至少需要一个）：

• username：sAMA帐户名称
• user_dn：可分辨名称
• email：电子邮件地址

示例:

Get user information for username "jdoe"

修改用户

修改用户属性。

参数:

• user_dn （必填）：用户的可分辨名称
• display_name （可选）：显示名称
• mail （可选）：电子邮件地址
• telephone_number （可选）：电话号码
• title （可选）：职位名称
• department （可选）：部门
• company （可选）：公司名称

示例:

Update the email for user "CN=John Doe,OU=Users,DC=example,DC=com"
to "john.doe@example.com"

停用用户

禁用用户帐户。

参数:

• user_dn （必填）：用户的可分辨名称

示例:

Disable user account "CN=John Doe,OU=Users,DC=example,DC=com"

enable_user

启用用户帐户。

参数:

• user_dn （必填）：用户的可分辨名称

重置密码

重置用户密码。

参数:

• user_dn （必填）：用户的可分辨名称
• new_password （必填）：新密码（最少12个字符，需要复杂性）

示例:

Reset password for "CN=John Doe,OU=Users,DC=example,DC=com" to "NewSecure123!"

删除用户

从Active Directory中删除用户。

参数:

• user_dn （必填）：用户的可分辨名称

示例:

Delete user "CN=Test User,OU=Users,DC=example,DC=com"

搜索用户

在Active Directory中搜索用户。

参数:

• username （可选）：按用户名筛选
• email （可选）：按电子邮件筛选
• enabled_only （可选）：仅返回已启用的帐户（默认值：false）
• max_results （可选）：最大结果（默认值：100）

示例:

Search for all enabled users in the domain

安全考虑

LDAP注入预防

所有用户输入都经过验证和净化，以防止LDAP注入攻击。特殊LDAP字符已正确转义。

安全连接

在生产中始终使用LDAPS（端口636）。服务器默认执行SSL/TLS并验证证书。

凭据管理

• 永不承诺 .env 文件到版本控制
• 使用具有最低权限的专用服务帐户
• 定期轮换服务帐户密码
• 考虑在生产环境中使用Azure密钥库或HashiCorp密钥库

审计日志

所有AD修改都会记录时间戳和受影响的对象。检查 logs/ad-audit.log 用于审计跟踪。

发展

运行测试

pytest tests/

代码格式化

black src/

类型检查

mypy src/

代码检查

ruff check src/

故障排除

连接问题

• 验证AD服务器主机名和端口
• 检查防火墙规则是否允许LDAPS（端口636）
• 确保服务帐户凭据正确
• 测试LDAP连接 ldp.exe 或 ldapsearch

证书错误

• 如果使用自签名证书，请设置 AD_VERIFY_CERT=false （不建议用于生产）
• 或者在中提供CA证书的路径 AD_CERT_PATH

权限错误

• 验证服务帐户在AD中是否具有所需的权限
• 检查目标OU的控制委托
• 查看AD安全日志以了解拒绝访问事件

密码复杂性错误

• 确保密码符合域密码策略
• 默认要求：最少12个字符，4种字符类型中的3种
• 调整 PASSWORD_MIN_LENGTH 在 .env 如有需要

项目结构

D:\repo1\
├── src/
│   ├── main.py                 # MCP server entry point
│   ├── ad_connector.py         # LDAP connection management
│   ├── types.py                # Type definitions
│   ├── tools/
│   │   └── user_tools.py       # User management functions
│   └── utils/
│       ├── validators.py       # Input validation
│       ├── ldap_utils.py       # LDAP helpers
│       └── formatters.py       # Output formatting
├── tests/                      # Test suite
├── logs/                       # Log files
├── pyproject.toml              # Project configuration
├── .env.example                # Environment template
└── README.md                   # This file

贡献

欢迎投稿！拜托：

1. 遵循PEP 8风格指南
2. 为所有函数添加类型提示
3. 为新功能编写测试
4. 更新文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• 检查 克劳德。医学博士 详细实施说明文件
• 查看登录 logs/ 目录
• 在GitHub上打开一个问题

路线图

未来的增强功能：

• \[\]组管理工具（创建、修改、添加/删除成员）
• \[\]OU管理（创建、移动对象）
• \[\]计算机帐户管理
• \[\]批量用户操作
• \[\]资源和提示模板
• \[\]用于高级操作的PowerShell集成
• \[\]支持Azure AD/Entra ID