Koppla

Koppla 是一个用于 Active Directory 的 模型-上下文-协议服务器，使您能够使用自然语言管理用户、组和计算机对象。

<img src="https://github.com/ruudmens/Koppla/blob/main/assets/Koppla-demo.gif?raw=true" alt="Koppla Demo" width="500"/>

更多信息，请访问 https://lazyadmin.nl/koppla

使用 Koppla，您可以使用 Claude Desktop 或其他支持 MCP 的 AI 代理无缝地查询和管理您的 Active Directory 环境。

---

🔹 Koppla 能做什么？

Koppla 允许您轻松执行复杂的 Active Directory 查询和更新。 示例：

• “查找所有 90 天未登录的非活动用户。”
• “将 John Doe 添加到 'IT Admins' 安全组。”
• “列出所有锁定的用户帐户。”
• “查找销售部门的所有用户。”
• “Jane Smith 属于哪些组？”
• “显示空组。”
• “查找属于 A 组但不属于 B 组的用户。”

---

🚀 入门

1️⃣ 先决条件

• Python 3.7 或更高版本
• Active Directory 环境
• Claude Desktop 应用程序（用于与 Claude 集成）

2️⃣ 安装

Koppla 需要 Python，可以使用以下命令安装：

pip install koppla

3️⃣ 配置

使用配置管理器（推荐）

Koppla 包含一个安全的配置管理器，用于处理敏感凭据的加密：

koppla-config configure

这个交互式工具将：

1. 提示您输入 Active Directory 连接详细信息
2. 使用 Fernet 对称加密安全地加密您的密码
3. 使用 Koppla 服务器设置创建或更新 Claude Desktop 配置文件
4. 自动创建现有 Claude Desktop 配置的备份
5. 测试连接以验证您的凭据

您还可以：

• 显示当前配置：koppla-config show
• 测试您的 AD 连接：koppla-config test

手动配置

Koppla 使用环境变量进行配置：

名称	描述
AD_SERVER	Active Directory 服务器的地址。
AD_USER	用于身份验证的用户名。
AD_PASSWORD	用于身份验证的密码。
BASE_DN	LDAP 查询的基本 DN。
AD_WRITE_ENABLED	启用或禁用写入操作（true/false）。

---

要使用 Claude Desktop 应用程序手动配置 Koppla，请将以下配置添加到您的 claude_desktop_config.json 的 "mcpServers" 部分：

{
  "mcpServers": {
    "Koppla-Active-Directory": {
        "command": "python",
        "args": ["-m", "koppla.server"],
        "env": {
            "AD_SERVER": "ldap://<domain-controller-name>:389",
            "AD_USER": "<domain\\username>",
            "AD_PASSWORD": "<password>",
            "BASE_DN": "DC=lazyadmin,DC=nl",
            "AD_WRITE_ENABLED": "false"
        }
    }
  }
}

⚠️ 数据处理和隐私声明

重要提示：Koppla 将 Active Directory 数据传输到外部 AI 模型进行处理。 这可能具有安全和合规性影响，特别是对于受 GDPR 或类似法规约束的组织。 Koppla 本身不存储任何 AD 数据，但请注意，AI 代理可能会根据其自身策略保留对话历史记录。 确保使用符合您组织的数据处理要求，并考虑通过仔细配置来限制可查询数据的范围。

🔒 安全特性

密码加密

• Koppla 使用 Fernet 对称加密（来自 cryptography 包）来保护您的 Active Directory 密码
• 加密密钥与配置分开存储在具有受限权限的密钥文件中
• 使用配置管理器时，密码永远不会以纯文本形式存储
• 加密密码在配置文件中显示为 ENCRYPTED:xxxx...

备份系统

• 在任何配置更改之前，Koppla 会自动创建 Claude Desktop 配置的带时间戳的备份
• 备份与您的配置一起存储，格式为：claude_desktop_config.json.backup_YYYYMMDD_HHMMSS

写保护

• 默认情况下，所有写入操作（从组中添加/删除用户、更新用户属性）均已禁用
• 要启用写入操作，请将 AD_WRITE_ENABLED 设置为 "true"
• 无论写入设置如何，关键帐户和组都具有额外的保护

支持的写入操作

当 AD_WRITE_ENABLED 设置为 "true" 时，Koppla 支持以下写入操作：

1. 更新用户属性

   • 修改标准用户属性，如描述、职称、部门等。
   • 无法修改受保护的字段（密码、安全标识符、帐户控制）
   • 无法修改受保护的帐户（管理员、服务帐户等）

2. 将用户添加到组

   • 将标准用户添加到安全组或通讯组
   • 无法将用户添加到受保护的管理组
   • 受保护的帐户无法添加到任何组

3. 从组中删除用户

   • 从大多数安全组或通讯组中删除用户
   • 无法从关键系统组中删除用户
   • 受保护的帐户无法从任何组中删除

所有写入操作都需要在执行前进行明确确认。