ActiveDirectoryMCP-增强型Active Directory MCP服务器

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

🚀 特性

👥 完整的用户管理

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

🔐 高级集团管理

创建和管理安全和通讯组
组范围管理（全局、域本地、通用）
成员添加和删除
嵌套组分析
集团成员报告

💻 计算机帐户管理

创建和管理计算机对象
计算机帐户生命周期管理
陈旧电脑检测
计算机组成员资格
服务负责人姓名管理

🏢 组织单位运营

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

🛡️ 安全和审计工具

域安全策略分析
特权组监控
非活动用户检测
密码策略合规性检查
行政账目审计
权限分析和报告

🌐 多种运输方式

标准运输：传统MCP通信
HTTP传输：端口8813上基于FastMCP的HTTP传输
Docker部署：生产就绪的集装箱化
MCP检查员：与调试工具兼容

🧪 质量保证

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

📋 先决条件

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

🛠️ 安装

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

克隆和设置环境：

   # Clone repository
   git clone https://github.com/alpadalar/ActiveDirectoryMCP.git
   cd ActiveDirectoryMCP

   # Create and activate virtual environment
   uv venv
   source .venv/bin/activate  # Linux/macOS
   # OR
   .\.venv\Scripts\Activate.ps1  # Windows

安装依赖项：

   # Install with development dependencies
   uv pip install -e ".[dev]"

创建配置：

   # Create config directory and copy template
   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"
       }
   }

验证安装

# Test configuration
python -c "import active_directory_mcp; print('Installation OK')"

# Run tests
pytest

# Test LDAP connection
AD_MCP_CONFIG="ad-config/ad-config.json" python -m active_directory_mcp.server

🚀 运行服务器

🏭 生产部署

使用现有的Active Directory部署到生产环境：

# 1. Configure for your AD environment
cp ad-config/production-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD server details

# 2. Deploy ActiveDirectoryMCP
docker compose up -d

# 3. Verify deployment
docker compose ps
docker compose logs activedirectory-mcp

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

生产特点：

✅ 连接到现有的AD基础架构
✅ SSL/TLS安全
✅ 资源限制和健康检查
✅ 生产测井

🧪 开发/测试环境

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

# 1. Start test environment
docker compose -f docker-compose-ad.yml up -d

# 2. Test the setup
python test_ad_environment.py

# 3. Access services
# - ActiveDirectoryMCP: http://localhost:8813/activedirectory-mcp
# - LDAP Admin: http://localhost:8080

测试特点：

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

开发模式（标准）

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

# Start stdio server
./start_server.sh

# Or with custom config
AD_MCP_CONFIG="ad-config/ad-config.json" python -m active_directory_mcp.server

HTTP模式（本地开发）

对于本地HTTP传输开发：

# Start HTTP server
./start_http_server.sh

# Or with custom settings
python -m active_directory_mcp.server_http --host 0.0.0.0 --port 8813 --path /activedirectory-mcp

🔧 游标/VS代码集成

选项1:Docker Compose（推荐）

{
    "mcpServers": {
        "ActiveDirectoryMCP": {
            "transport": {
                "type": "http",
                "url": "http://localhost:8813/activedirectory-mcp"
            },
            "description": "Active Directory Management with HTTP Transport"
        }
    }
}

选项2：本地HTTP服务器

{
    "mcpServers": {
        "ActiveDirectoryMCP-Local": {
            "transport": {
                "type": "http",
                "url": "http://localhost:8813/activedirectory-mcp"
            },
            "description": "ActiveDirectoryMCP Local Development"
        }
    }
}

选项3：传统标准（遗留）

{
    "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 -列出具有层次结构的OU
get_organizational_unit -获取OU详细信息
create_organizational_unit -创建新OU
modify_organizational_unit -更新OU属性
delete_organizational_unit -删除OU
move_organizational_unit -移动OU
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项测试通过

运行单元测试

# Run all tests with verbose output
pytest -v

# Run specific test categories
pytest tests/test_config.py -v                    # Configuration tests
pytest tests/test_ldap_manager.py -v              # LDAP manager tests
pytest tests/test_user_tools.py -v                # User management tests
pytest tests/test_group_tools.py -v               # Group management tests  
pytest tests/test_computer_tools.py -v            # Computer management tests
pytest tests/test_security_tools.py -v            # Security & audit tests
pytest tests/test_organizational_unit_tools.py -v # OU management tests
pytest tests/test_integration.py -v               # End-to-end workflow tests
pytest tests/test_performance.py -v               # Performance & load tests

测试HTTP服务器

# Test HTTP endpoints directly
python test_scripts/test_http_server.py

# Custom server URL
python test_scripts/test_http_server.py http://your-server:8813/activedirectory-mcp

运行集成测试

# Test with real AD connection (requires config)
AD_MCP_CONFIG="ad-config/ad-config.json" pytest tests/test_integration.py -v

运行性能测试

# Run performance and load tests
pytest tests/test_performance.py -v

# Run specific performance categories
pytest tests/test_performance.py::TestLargeDatasetPerformance -v      # Large dataset handling
pytest tests/test_performance.py::TestConcurrentOperations -v         # Concurrent operations
pytest tests/test_performance.py::TestMemoryAndResourceUsage -v       # Memory usage tests
pytest tests/test_performance.py::TestStressScenarios -v              # Stress testing

# Performance test features:
# - Large dataset performance (10K+ users/groups)
# - Concurrent operation testing (50+ simultaneous queries) 
# - Memory usage validation
# - Sustained load scenarios
# - Connection pooling efficiency

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

# Start LDAP/AD test environment 
docker-compose -f docker-compose-ad.yml up -d

# Wait for services to be ready (30 seconds)
docker logs -f openldap-ad-dc

# Test ActiveDirectoryMCP with test environment
python test_ad_environment.py

# Expected output:
# ✅ Connected to LDAP: 192.168.1.100:389
# ✅ MCP Config: SUCCESS
# ✅ HTTP API: SUCCESS
# 🎉 Test environment ready!

测试环境特征：

🔗 具有AD风格结构的LDAP目录服务
👥 测试用户：admin、jdoe、jsmith、mwilson、testadmin
🔐 测试组：IT部门、销售团队、市场营销、所有用户
🖥️ Web管理员：http://localhost:8080（cn=管理员，dc=测试，dc=本地/Admin123！）
📚 完整测试指南：测试指南.md

测试HTTP API

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

# List users
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/                          # Source code
│   └── active_directory_mcp/
│       ├── server.py                # Main MCP server (stdio)
│       ├── server_http.py           # HTTP MCP server
│       ├── config/                  # Configuration handling
│       ├── core/                    # Core functionality
│       │   ├── ldap_manager.py     # LDAP connection manager
│       │   └── logging.py          # Logging configuration
│       └── tools/                   # Tool implementations
│           ├── user.py             # User management
│           ├── group.py            # Group management
│           ├── computer.py         # Computer management
│           ├── organizational_unit.py # OU management
│           └── security.py         # Security & audit tools
│
├── 📁 tests/                       # Comprehensive test suite (129 tests)
│   ├── test_config.py              # Configuration tests (8)
│   ├── test_ldap_manager.py        # LDAP manager tests (12)
│   ├── test_user_tools.py          # User management tests (13)
│   ├── test_group_tools.py         # Group management tests (17)
│   ├── test_computer_tools.py      # Computer management tests (18)
│   ├── test_security_tools.py      # Security & audit tests (14)
│   ├── test_organizational_unit_tools.py # OU management tests (18)
│   ├── test_integration.py         # End-to-end workflow tests (20)
│   └── test_performance.py         # Performance & load tests (9)
├── 📁 ad-config/                   # Configuration files
│   ├── ad-config.json             # Main server configuration
│   ├── config.example.json        # Example configuration
│   └── production-config.example.json # Production example
│
├── 📄 Configuration Files
│   ├── pyproject.toml             # Project metadata
│   ├── docker-compose.yml         # Production deployment
│   ├── docker-compose-ad.yml      # Test environment with LDAP
│   ├── Dockerfile                 # Container definition
│   └── requirements.in            # Dependencies
│
└── 📄 Scripts
    ├── start_server.sh            # Stdio server launcher
    └── start_http_server.sh       # HTTP server launcher

🔍 故障排除

✅ 最近修复（v0.1.0）

LDAP3兼容性：修复了TLS配置与最新ldap3库的兼容性
测试套件：所有43项测试现在都成功通过（成功率100%）
模拟问题：解决了错误场景的集成测试模拟问题
安全配置：删除了弃用的LDAP参数以提高兼容性

常见问题

LDAP连接失败

   # Test connectivity
   ldapsearch -H ldap://dc.example.com -D "CN=user,DC=example,DC=com" -W -b "DC=example,DC=com" "(objectClass=domain)"

权限不足

- 验证服务帐户权限 - 检查OU访问权限 - 确保LDAP绑定DN正确

SSL/TLS问题

   # Test SSL connection
   openssl s_client -connect dc.example.com:636 -showcerts

端口已在使用中

   # Check port usage
   netstat -tlnp | grep 8813
   # Change port if needed
   HTTP_PORT=8814 ./start_http_server.sh

⚠️ LLM工具限制警告

一些LLM模型在使用40多种工具时可能会遇到问题。

查看日志

# Container logs
docker logs activedirectory-mcp -f

# Local logs
tail -f active_directory_mcp.log

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

灵感源自 ProxmoxMCP扩展
使用模型上下文协议（MCP）SDK构建
由ldap3库支持的LDAP集成
FastMCP用于HTTP传输功能

______________________________________________________________________

✅ 生产准备就绪！ 🎉 您的全面Active Directory MCP服务经过全面测试（通过129/129测试），并已准备好进行生产部署，具有完整的HTTP传输支持、性能验证和企业级可靠性。

🔗 相关项目

ProxmoxMCP扩展 -Proxmox虚拟化管理
模型上下文协议 -MCP官方文件
FastMCP -用于HTTP传输的FastMCP

Active Directory MCP

快速接入

详细介绍