活动目录MCP

Name: 活动目录MCP
Author: alpadalar

作者：alpadalar7 星标更新：2025-10-30

安装使用来源：spider==github.com

项目介绍

ActiveDirectoryMCP - 增强型Active Directory MCP服务器

这是一个基于Python的模型上下文协议（MCP）服务器，用于通过LDAP管理Active Directory环境。该项目提供了强大的工具，用于用户管理、组操作、计算机账户管理、组织单位管理和安全审计。

🚀 特性

👥 完整的用户管理

创建、修改和删除用户账户
密码管理和重置功能
启用/禁用用户账户
组成员分析
用户权限审计

🔐 高级组管理

创建和管理安全和分发组
组作用域管理（全局、域本地、通用）
成员添加和移除
嵌套组分析
组成员报告

💻 计算机账户管理

创建和管理计算机对象
计算机账户生命周期管理
过期计算机检测
计算机组成员关系
服务主体名称管理

🏢 组织单位操作

创建、修改和删除OUs
OU层次结构管理
在OUs之间移动对象
OU内容分析
组策略链接信息

🛡️ 安全与审计工具

域安全策略分析
特权组监控
不活跃用户检测
密码策略合规检查
管理员账户审计
权限分析和报告

🌐 多种传输选项

Stdio传输：传统的MCP通信
HTTP传输：基于FastMCP的HTTP传输，端口8813
Docker部署：生产就绪容器化
MCP Inspector：兼容调试工具

🧪 质量保证

129/129测试通过：所有模块100%测试成功
全面测试覆盖：所有5个工具模块完全测试
LDAP3兼容：确保最新库兼容性
生产就绪：彻底测试和验证
企业级测试：单元、集成和性能测试
全面覆盖：配置、LDAP、工具、工作流和性能
Samba AD测试环境：使用真实AD协议进行测试

📋 先决条件

Python 3.9或更高版本
UV包管理器（推荐）或pip
具有适当权限的Active Directory访问
到域控制器的LDAP/LDAPS连接性

🛠️ 安装

选项1：快速安装（推荐）

克隆并设置环境：

# 克隆仓库
git clone https://github.com/alpadalar/ActiveDirectoryMCP.git
cd ActiveDirectoryMCP

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# 或
.\.venv\Scripts\Activate.ps1  # Windows

安装依赖项：

# 安装带有开发依赖项
uv pip install -e ".[dev]"

创建配置：

# 创建配置目录并复制模板
mkdir -p ad-config
cp ad-config/config.example.json ad-config/config.json

配置Active Directory连接：

{
    "active_directory": {
        "server": "ldap://dc.example.com:389",
        "domain": "example.com",
        "base_dn": "DC=example,DC=com",
        "bind_dn": "CN=service-account,OU=Service Accounts,DC=example,DC=com",
        "password": "your-service-account-password"
    },
    "organizational_units": {
        "users_ou": "OU=Users,DC=example,DC=com",
        "groups_ou": "OU=Groups,DC=example,DC=com",
        "computers_ou": "OU=Computers,DC=example,DC=com",
        "service_accounts_ou": "OU=Service Accounts,DC=example,DC=com"
    }
}

验证安装

# 测试配置
python -c "import active_directory_mcp; print('安装OK')"

# 运行测试
pytest

# 测试LDAP连接
AD_MCP_CONFIG="ad-config/ad-config.json" python -m active_directory_mcp.server

🚀 运行服务器

🏭 生产部署

在现有Active Directory上部署到生产：

# 1. 配置您的AD环境
cp ad-config/production-config.example.json ad-config/ad-config.json
# 使用您的AD服务器详细信息编辑ad-config.json

# 2. 部署ActiveDirectoryMCP
docker compose up -d

# 3. 验证部署
docker compose ps
docker compose logs activedirectory-mcp

🌐 生产URL: http://localhost:8813/activedirectory-mcp

生产特性：

✅ 连接到现有的AD基础设施
✅ SSL/TLS安全性
✅ 资源限制及健康检查
✅ 生产日志

🧪 开发/测试环境

对于包含测试LDAP服务器的开发：

# 1. 启动测试环境
docker compose -f docker-compose-ad.yml up -d

# 2. 测试设置
python test_ad_environment.py

# 3. 访问服务
# - ActiveDirectoryMCP: http://localhost:8813/activedirectory-mcp
# - LDAP管理员: http://localhost:8080

测试特性：

✅ 包含OpenLDAP测试服务器
✅ 预配置测试数据
✅ 基于Web的LDAP管理
✅ 不需要外部AD

开发模式（Stdio）

对于使用stdio传输的测试和开发：

# 启动stdio服务器
./start_server.sh

# 或使用自定义配置
AD_MCP_CONFIG="ad-config/ad-config.json" python -m active_directory_mcp.server

HTTP模式（本地开发）

对于本地HTTP传输开发：

# 启动HTTP服务器
./start_http_server.sh

# 或使用自定义设置
python -m active_directory_mcp.server_http --host 0.0.0.0 --port  8813 --path /activedirectory-mcp

🔧 Cursor/VS Code集成

选项1：Docker Compose（推荐）

{
    "mcpServers": {
        "ActiveDirectoryMCP": {
            "transport": {
                "type": "http",
                "url": "http://localhost:8813/activedirectory-mcp"
            },
            "description": "使用HTTP传输的Active Directory管理"
        }
    }
}

选项2：本地HTTP服务器

{
    "mcpServers": {
        "ActiveDirectoryMCP-Local": {
            "transport": {
                "type": "http",
                "url": "http://localhost:8813/activedirectory-mcp"
            },
            "description": "ActiveDirectoryMCP本地开发"
        }
    }
}

选项3：传统Stdio（遗留）

{
    "mcpServers": {
        "ActiveDirectoryMCP": {
            "command": "/absolute/path/to/ActiveDirectoryMCP/.venv/bin/python",
            "args": ["-m", "active_directory_mcp.server"],
            "cwd": "/absolute/path/to/ActiveDirectoryMCP",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ActiveDirectoryMCP/src",
                "AD_MCP_CONFIG": "/absolute/path/to/ActiveDirectoryMCP/ad-config/ad-config.json"
            },
            "disabled": false
        }
    }
}

📚 可用工具及操作

👥 用户管理

list_users - 列出用户，带过滤和属性
get_user - 获取详细用户信息
create_user - 创建新用户账户
modify_user - 更新用户属性
delete_user - 删除用户账户
enable_user / disable_user - 账户状态管理
reset_user_password - 密码重置功能
get_user_groups - 组成员分析

🔐 组管理

list_groups - 列出组，带过滤
get_group - 获取详细组信息
create_group - 创建安全/分发组
modify_group - 更新组属性
delete_group - 删除组
add_group_member / remove_group_member - 成员管理
get_group_members - 成员列表，带递归

💻 计算机管理

list_computers - 列出计算机账户
get_computer - 获取计算机详情
create_computer - 创建计算机对象
modify_computer - 更新计算机属性
delete_computer - 删除计算机账户
enable_computer / disable_computer - 账户管理
reset_computer_password - 密码重置
get_stale_computers - 查找不活跃计算机

🏢 组织单位管理

list_organizational_units - 列出OUs，带层次结构
get_organizational_unit - 获取OU详情
create_organizational_unit - 创建新的OUs
modify_organizational_unit - 更新OU属性
delete_organizational_unit - 删除OUs
move_organizational_unit - 移动OUs
get_organizational_unit_contents - 列出OU内容

🛡️ 安全与审计

get_domain_info - 域安全设置
get_privileged_groups - 特权组分析
get_user_permissions - 用户权限分析
get_inactive_users - 不活跃用户检测
get_password_policy_violations - 策略合规
audit_admin_accounts - 管理员账户审计

🔧 系统工具

test_connection - LDAP连接性测试
health - 服务器健康检查
get_schema_info - 工具模式信息

⚠️ 注意：ActiveDirectoryMCP提供总共42个工具。某些LLM模型可能无法处理如此多的工具。

🔒 安全配置

服务账户设置

在AD中创建专用服务账户
授予最低必需权限：
- 对域的读取访问权限
- 用户/组/计算机管理权限
- 密码重置权限（如果需要）

SSL/TLS配置

{
    "active_directory": {
        "server": "ldaps://dc.example.com:636",
        "use_ssl": true
    },
    "security": {
        "enable_tls": true,
        "validate_certificate": true,
        "ca_cert_file": "/path/to/ca-certificate.pem"
    }
}

连接池配置

{
    "performance": {
        "connection_pool_size": 10,
        "max_retries": 3,
        "retry_delay": 1.0,
        "page_size": 1000
    }
}

🧪 测试

✅ 所有测试通过（129/129） - 生产就绪！

快速测试状态

配置测试：8/8 ✅
用户工具测试：13/13 ✅
组工具测试：17/17 ✅
计算机工具测试：18/18 ✅
安全工具测试：14/14 ✅
OU工具测试：18/18 ✅
LDAP管理器测试：12/12 ✅
集成测试：20/20 ✅（端到端工作流程）
性能测试：9/9 ✅（负载和压力测试）
总计：129/129测试通过

运行单元测试

# 以详细输出运行所有测试
pytest -v

# 运行特定测试类别
pytest tests/test_config.py -v                    # 配置测试
pytest tests/test_ldap_manager.py -v              # LDAP管理器测试
pytest tests/test_user_tools.py -v                # 用户管理测试
pytest tests/test_group_tools.py -v               # 组管理测试
pytest tests/test_computer_tools.py -v            # 计算机管理测试
pytest tests/test_security_tools.py -v            # 安全与审计测试
pytest tests/test_organizational_unit_tools.py -v # OU管理测试
pytest tests/test_integration.py -v               # 端到端工作流程测试
pytest tests/test_performance.py -v               # 性能与负载测试

测试HTTP服务器

# 直接测试HTTP端点
python test_scripts/test_http_server.py

# 自定义服务器URL
python test_scripts/test_http_server.py http://your-server:8813/activedirectory-mcp

运行集成测试

# 使用真实AD连接测试（需要配置）
AD_MCP_CONFIG="ad-config/ad-config.json" pytest tests/test_integration.py -v

运行性能测试

# 运行性能和负载测试
pytest tests/test_performance.py -v

# 运行特定性能类别
pytest tests/test_performance.py::TestLargeDatasetPerformance -v      # 大数据集处理
pytest tests/test_performance.py::TestConcurrentOperations -v         # 并发操作
pytest tests/test_performance.py::TestMemoryAndResourceUsage -v       # 内存使用测试
pytest tests/test_performance.py::TestStressScenarios -v              # 压力测试

# 性能测试特性：
# - 大数据集性能（10K+用户/组）
# - 并发操作测试（50+同时查询）
# - 内存使用验证
# - 持续负载场景
# - 连接池效率

🏢 使用LDAP/AD环境测试（推荐）

# 启动LDAP/AD测试环境
docker-compose -f docker-compose-ad.yml up -d

# 等待服务准备好（30秒）
docker logs -f openldap-ad-dc

# 使用测试环境测试ActiveDirectoryMCP
python test_ad_environment.py

# 预期输出：
# ✅ 连接到LDAP: 192.168.1.100:389
# ✅ MCP配置：成功
# ✅ HTTP API：成功
# 🎉 测试环境准备就绪！

测试环境特性：

🔗 类似AD结构的LDAP目录服务
👥 测试用户：admin, jdoe, jsmith, mwilson, testadmin
🔐 测试组：IT部门，销售团队，市场部，所有用户
🖥️ Web管理员：http://localhost:8080 (cn=admin,dc=test,dc=local / Admin123!)
📚 完整测试指南：TESTING_GUIDE.md

测试HTTP API

# 健康检查
curl -X POST "http://localhost:8813/activedirectory-mcp" \
  -H "Content-Type: application/json" \
  -d '{"method": "health", "params": {}}'

# 列出用户
curl -X POST "http://localhost:8813/activedirectory-mcp" \
  -H "Content-Type: application/json" \
  -d '{"method": "list_users", "params": {"ou": "OU=Users,DC=example,DC=com"}}'

📊 项目结构

ActiveDirectoryMCP/
├── 📁 src/                          # 源代码
│   └── active_directory_mcp/
│       ├── server.py                # 主MCP服务器（stdio）
│       ├── server_http.py           # HTTP MCP服务器
│       ├── config/                  # 配置处理
│       ├── core/                    # 核心功能
│       │   ├── ldap_manager.py     # LDAP连接管理器
│       │   └── logging.py          # 日志配置
│       └── tools/                   # 工具实现
│           ├── user.py             # 用户管理
│           ├── group.py            # 组管理
│           ├── computer.py         # 计算机管理
│           ├── organizational_unit.py # OU管理
│           └── security.py         # 安全与审计工具
│
├── 📁 tests/                       # 全面测试套件（129个测试）
│   ├── test_config.py              # 配置测试（8个）
│   ├── test_ldap_manager.py        # LDAP管理器测试（12个）
│   ├── test_user_tools.py          # 用户管理测试（13个）
│   ├── test_group_tools.py         # 组管理测试（17个）
│   ├── test_computer_tools.py      # 计算机管理测试（18个）
│   ├── test_security_tools.py      # 安全与审计测试（14个）
│   ├── test_organizational_unit_tools.py # OU管理测试（18个）
│   ├── test_integration.py         # 端到端工作流程测试（20个）
│   └── test_performance.py         # 性能与负载测试（9个）
├── 📁 ad-config/                   # 配置文件
│   ├── ad-config.json             # 主服务器配置
│   ├── config.example.json        # 示例配置
│   └── production-config.example.json # 生产示例
│
├── 📄 配置文件
│   ├── pyproject.toml             # 项目元数据
│   ├── docker-compose.yml         # 生产部署
│