Koppla

Koppla

Koppla 是一款用于 Active Directory 的 模型上下文协议服务，让你能够通过自然语言管理用户、组和计算机对象。

如需了解更多信息，请访问 https://lazyadmin.nl/koppla

借助 Koppla，你可以使用 Claude Desktop 或其他支持 MCP 的 AI Agent，轻松查询和管理 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. 创建或更新 Claude Desktop 配置文件，添加 Koppla 服务设置
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）。

---

若要手动配置 Koppla 与 Claude Desktop 应用的集成，请将以下配置添加到 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 Agent 可能会根据自身政策保留对话历史。请确保使用方式符合组织的数据处理要求，并考虑通过谨慎配置来限制可查询数据的范围。

🔒 安全功能

密码加密

• 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. 将用户从组中移除

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

所有写入操作都必须在执行前获得明确确认。