Skills MCP AD

Skills MCP AD

Multi-Client Active Directory MCP Server - Enterprise AD Management via AI

About • Architecture • Quick Start • Tools • Examples • Configuration

______________________________________________________________________

📖 关于本项目

技能MCP AD 是一个生产就绪的模型上下文协议（MCP）服务器，使Claude、ChatGPT和Gemini等AI助手能够安全地管理Active Directory环境。

由...建造 IT技能 经过真实MSP（托管服务提供商）作战测试，该MCP提供：

✨ 45个综合工具 实现完整的AD生命周期管理 🏢 多客户端架构 -从单个代码库管理多个AD域 🔒 企业级安全 -带有审计日志的承载令牌身份验证 ⚡ 生产测试 -部署在真实的MSP环境中 🚀 易于扩展 -使用自动脚本在几分钟内添加新的AD域

为什么技能MCP AD？

对于托管服务提供商（MSP）：

• 从一个平台管理多个客户端Active Directory域
• 隔离每个客户端的配置和凭据
• 随着客户群的增长，轻松扩展
• 将AD管理开销减少70%

对于IT团队：

• 通过自然语言实现人工智能驱动的广告操作
• 全面的工具集，涵盖用户、组、OU、计算机、GPO
• 与Claude Code和Gemini兼容的流式HTTP传输
• 自动化入职/离职工作流程

架构概述

┌─────────────────────────────────────────────────────────────────────────┐
│                     Claude / ChatGPT / Gemini                           │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ MCP Protocol (Streamable HTTP)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Skills MCP AD                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Users     │  │   Groups    │  │     OUs     │  │  Computers  │    │
│  │  (14 tools) │  │  (10 tools) │  │  (8 tools)  │  │  (7 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Password   │  │    GPOs     │  │   Search    │  │   Reports   │    │
│  │  (4 tools)  │  │  (3 tools)  │  │  (2 tools)  │  │  (5 tools)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ LDAP/LDAPS Protocol
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       Active Directory                                  │
│                    (Windows Server / Samba AD)                          │
└─────────────────────────────────────────────────────────────────────────┘

______________________________________________________________________

🏗️ 多客户端架构

MSP的游戏规则改变者： Skills MCP AD的独特架构允许您从单个代码库管理多个Active Directory域。

运作原理

┌─────────────────────────────────────────────────────────────────────────┐
│                         .base-code/                                     │
│                    (Shared Codebase)                                    │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │ Source Code (Python, FastAPI, LDAP3) - 45 Tools                 │   │
│  │ Single point of maintenance and updates                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
         │                          │                          │
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Client A       │      │  Client B       │      │  Client C       │
│  Port: 8850     │      │  Port: 8851     │      │  Port: 8852     │
│  Token: xxx     │      │  Token: yyy     │      │  Token: zzz     │
│  Config:        │      │  Config:        │      │  Config:        │
│  ad-config.json │      │  ad-config.json │      │  ad-config.json │
└─────────────────┘      └─────────────────┘      └─────────────────┘
         │                          │                          │
         ▼                          ▼                          ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  AD Domain A    │      │  AD Domain B    │      │  AD Domain C    │
│  company-a.com  │      │  company-b.com  │      │  company-c.com  │
└─────────────────┘      └─────────────────┘      └─────────────────┘

关键利益

✅ 单一代码库 -更新一次，部署到任何地方 ✅ 隔离配置 -每个客户端都有单独的凭据和令牌 ✅ 独立港口 -同时运行多个实例 ✅ 易于扩展 -在2分钟内添加新客户 ✅ 成本效益高 -一个部署可以处理无限的AD域

目录结构

active-directory/
├── .base-code/              # Shared source code (this repo)
│   ├── src/                 # Python MCP implementation
│   ├── requirements.txt     # Dependencies
│   └── README.md            # This file
│
├── client-a/                # Client A instance
│   └── ad-config/
│       └── ad-config.json   # Client A AD credentials & config
│
├── client-b/                # Client B instance
│   └── ad-config/
│       └── ad-config.json   # Client B AD credentials & config
│
└── scripts/
    └── install-client.sh    # Script to add new clients

______________________________________________________________________

💼 需要有关Active Directory或AI的帮助？ 技能IT-技术解决方案 专门从事IT基础设施，在以下方面拥有深厚的专业知识 Active Directory和Windows服务器我们的团队在以下方面拥有专业知识 人工智能 和 模型上下文协议（MCP），为自动化和系统集成提供完整的解决方案。 我们的服务： - ✅ Active Directory咨询和实施 - ✅ 为您的基础设施定制MCP开发 - ✅ 人工智能与企业系统的集成 - ✅ 用户和组管理自动化 - ✅ 专业培训和支持 📞 WhatsApp/电话： +55 63 3224-4925-巴西🇧🇷 🌐 网站： skillsit.com.br 📧 电子邮件： contato@skillsit.com.br *“将基础设施转变为智能”*

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.11+或Docker
• LDAP访问Active Directory
• 具有适当AD权限的服务帐户

安装（Docker-推荐）

# 1. Clone the repository
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Configure your Active Directory connection
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD server details

# 3. Start the server
docker-compose up -d

# 4. Verify it's running
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

预期响应：

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "timestamp": "2025-12-09T10:00:00.000Z"
}

安装（Python）

# 1. Clone and set up virtual environment
git clone https://github.com/DevSkillsIT/Skills-MCP-AD.git
cd Skills-MCP-AD
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure Active Directory
cp ad-config/ad-config.example.json ad-config/ad-config.json
# Edit ad-config.json with your AD credentials

# 4. Run the server
python -m src.server_http

连接到克劳德代码

# Add MCP server to Claude Code
claude mcp add --transport http ad http://localhost:8850/mcp \
  --headers "Authorization: Bearer your_token_here"

连接到Gemini CLI

编辑 ~/.gemini/settings.json:

{
  "mcpServers": {
    "ad": {
      "httpUrl": "http://localhost:8850/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      },
      "timeout": 30000
    }
  }
}

______________________________________________________________________

🧰 工具（45）

MCP AD提供的技能 45个综合工具 按功能区组织：

👥 用户管理（14个工具）

🔐 密码管理（4个工具）

🗂️ 集团管理（10个工具）

🏢 组织单位（8个工具）

💻 计算机管理（7个工具）

🎯 组策略对象（3个工具）

🔍 搜索和查询（2个工具）

📊 报告和审计（5个工具）

______________________________________________________________________

💡 使用示例

员工入职

"Create a new user John Smith with username jsmith, email jsmith@company.com,
add to Sales group and VPN-Users group, and set password to Welcome2025!
with password change required at first login"

AI执行：

1. create_user -在默认OU中创建用户
2. add_user_to_groups -增加销售和VPN用户
3. force_password_change -强制更改密码

员工离职

"Disable user carlos.souza, remove from all groups,
and move to Terminated-Users OU"

AI执行：

1. disable_user -禁用帐户
2. get_user_groups -列出当前组
3. remove_user_from_groups -删除所有成员资格
4. move_object -移动到适当的OU

密码重置

"Reset password for maria.santos to TempPass123!
and require password change at next login"

AI执行：

1. unlock_user -如果锁定，则解锁
2. reset_password -设置新密码
3. force_password_change -执行变更政策

安全审计

"Show me all Domain Admins and users who haven't
logged in for more than 90 days"

AI执行：

1. get_domain_admins -列出特权帐户
2. get_inactive_users -查找过期帐户（90天以上）

批量用户创建

"Create these users in the Finance group with password Company@2025
and force password change:
- Ana Costa (ana.costa)
- Bruno Lima (bruno.lima)
- Carla Dias (carla.dias)"

AI执行：

1. create_user -创建每个用户
2. set_password -设置初始密码
3. add_user_to_groups -添加到财务组
4. force_password_change -执行政策

陈旧电脑清理

"Find all computers that haven't connected to the domain
in 6 months and show their details"

AI执行：

1. get_stale_computers -查找非活动计算机（180+天）
2. get_computer -获取每个的详细信息

______________________________________________________________________

⚙️ 配置

配置文件结构

创建 ad-config/ad-config.json:

{
  "ldap_server": "ldap://dc.yourdomain.com",
  "ldap_port": 389,
  "use_ssl": false,
  "base_dn": "DC=yourdomain,DC=com",
  "bind_user": "CN=MCPService,CN=Users,DC=yourdomain,DC=com",
  "bind_password": "YourSecurePassword123!",
  "default_user_ou": "OU=Users,DC=yourdomain,DC=com",
  "default_group_ou": "OU=Groups,DC=yourdomain,DC=com",
  "default_computer_ou": "OU=Computers,DC=yourdomain,DC=com",
  "auth_token": "your_secure_bearer_token_here"
}

配置参数

SSL/TLS配置（生产）

对于生产部署，请使用LDAPS：

{
  "ldap_server": "ldaps://dc.yourdomain.com",
  "ldap_port": 636,
  "use_ssl": true,
  "validate_cert": true,
  "ca_cert_path": "/path/to/ca-certificate.pem"
}

服务帐户权限

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

读取操作（最小值）：

• ✅ 读取域根目录上的所有属性
• ✅ 在域根目录上列出内容

写入操作（如果需要）：

• ✅ 在用户OU上创建/删除用户对象
• ✅ 在组OU上创建/删除组对象
• ✅ 在计算机OU上创建/删除计算机对象
• ✅ 重置用户OU上的密码
• ✅ 在特定OU上写入所有属性

安全最佳实践：

• 创建专用服务帐户（例如。， MCPService)
• 授予用例所需的最低权限
• 在生产中使用LDAPS
• 旋转 bind_password 和 auth_token 定期
• 限制对MCP服务器的网络访问

______________________________________________________________________

🏢 多客户端管理

添加新客户

使用附带的脚本在几分钟内添加新的AD域：

# Syntax: ./scripts/install-client.sh   

cd /opt/mcp-servers/active-directory

# Example: Add ACME Corporation on port 8853
./scripts/install-client.sh acme-corp "ACME Corporation" 8853

脚本的作用：

1. 创建客户端目录结构： acme-corp/ad-config/
2. 生成配置模板： ad-config.json
3. 创建PM2进程配置
4. 在指定端口上注册新的MCP实例

港口分配策略

多客户端部署的标准端口分配：

配置隔离

每个客户端都完全隔离：

• ✅ AD凭据(bind_user, bind_password)
• ✅ 身份验证令牌(auth_token)
• ✅ LDAP连接设置
• ✅ 对象创建的默认OU

过程管理（PM2）

# List all MCP AD instances
pm2 list | grep mcp-ad

# View logs for specific client
pm2 logs mcp-ad-client1

# Restart specific client
pm2 restart mcp-ad-client1

# Restart all AD MCP instances
pm2 restart all

更新共享代码库

更新时 .base-code/，所有客户端自动使用新代码：

cd .base-code/
git pull origin main

# Restart all instances to apply updates
pm2 restart all

______________________________________________________________________

🔐 安全

认证

所有请求都需要承载令牌身份验证：

Authorization: Bearer your_secure_token_here

生成安全令牌：

# Linux/Mac
openssl rand -hex 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

安全最佳实践

✅ 在生产中使用LDAPS -加密LDAP流量（端口636） ✅ 轮换凭据 -更改 auth_token 和 bind_password 季度的 ✅ 最低权限 -服务帐户应具有最低权限 ✅ 网络限制 -防火墙MCP服务器只允许IP ✅ 审核日志记录 -启用详细的日志记录以实现合规性 ✅ 秘密管理 -使用环境变量或机密管理器

审计日志

所有操作都记录在：

• ⏰ 时间戳
• 👤 经过身份验证的用户/令牌
• 🎯 执行的操作（工具名称+参数）
• ✅ 结果（成功/失败）
• 🌐 源地址

查看日志：

# Docker deployment
docker-compose logs -f skills-mcp-ad

# Python deployment
tail -f logs/mcp-ad.log

______________________________________________________________________

🧪 测试

健康检查

# Test server health and LDAP connectivity
curl http://localhost:8850/health \
  -H "Authorization: Bearer your_token_here"

预期响应：

{
  "status": "healthy",
  "ldap_connected": true,
  "domain": "yourdomain.com",
  "base_dn": "DC=yourdomain,DC=com",
  "timestamp": "2025-12-09T10:00:00.000Z",
  "tools_count": 45
}

测试MCP协议

# List available tools
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

测试用户列表

# List domain users
curl -X POST http://localhost:8850/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "ad_list_users_with_filters",
      "arguments": {
        "max_results": 10
      }
    },
    "id": 2
  }'

______________________________________________________________________

🔧 故障排除

常见问题

调试模式

启用详细的LDAP操作日志记录：

Docker：

# docker-compose.yml
environment:
  - LOG_LEVEL=DEBUG

python

export LOG_LEVEL=DEBUG
python -m src.server_http

验证LDAP连接

# Test LDAP bind from command line
ldapsearch -H ldap://dc.domain.com:389 \
  -D "CN=MCPService,CN=Users,DC=domain,DC=com" \
  -W \
  -b "DC=domain,DC=com" \
  "(objectClass=domain)"

检查端口可用性

# Linux/Mac
lsof -i :8850

# Windows
netstat -an | findstr :8850

______________________________________________________________________

🤝 贡献

我们欢迎社区的贡献！无论是bug报告、功能请求还是代码贡献。

开发设置

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Skills-MCP-AD.git
cd Skills-MCP-AD

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 3. Install development dependencies
pip install -r requirements-dev.txt

# 4. Configure test AD (or use Samba AD test container)
cp ad-config/ad-config.example.json ad-config/ad-config.json

# 5. Run tests
pytest tests/ -v

# 6. Run linter
ruff check .

# 7. Run formatter
black .

测试更改

# Run specific test categories
pytest tests/test_user_tools.py -v
pytest tests/test_group_tools.py -v
pytest tests/test_security.py -v

# Run with coverage
pytest --cov=src --cov-report=html

承诺标准

我们遵循常规承诺：

feat: add GPO management tools
fix: resolve LDAP timeout issue
docs: update configuration examples
refactor: improve error handling in user tools
test: add integration tests for password reset

拉取请求流程

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'feat: add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开一个带有清晰描述的拉取请求

______________________________________________________________________

📄 许可证

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

您可以自由地：

• ✅ 商业用途
• ✅ 修改
• ✅ 分发
• ✅ 私下使用

______________________________________________________________________

🙏 致谢

• 内置于 模型上下文协议 （MCP）SDK
• LDAP集成由 ldap3 图书馆
• 通过HTTP传输 快速API
• 受MSP运营中更好的AD自动化需求的启发

______________________________________________________________________

📞 支持

获取帮助

• 🐛 Bug报告：
• 💬 讨论：
• 📧 电子邮件： contato@skillsit.com.br
• 🌐 网站： skillsit.com.br

关于技能IT

IT技能 - 技术解决方案 是一家巴西技术公司，专门从事MSP解决方案和人工智能自动化工具。

我们构建MCP服务器，使IT团队和MSP能够通过AI助手更有效地管理其基础设施。

我们的MCP生态系统

联系

• 📱 电话： +55 (51) 98049-2520
• 📧 电子邮件： contato@skillsit.com.br
• 🌐 网站： skillsit.com.br
• 💼 github： @DevSkillsIT
• 📍 地点： 巴西卡诺阿斯/RS🇧🇷

______________________________________________________________________

制造于❤️ by Skills IT - IT解决方案 - 中国

*赋予MSP智能自动化能力*

⬆ 返回页首