Koppla

Koppla is a model-context-protocol (MCP) server that enables you to manage Active Directory objects using natural language through Claude Desktop or other MCP-capable AI agents. It exposes queries and updates for users, groups, and computer objects, allowing you to ask questions like finding inactive users, listing group memberships, showing empty groups, or updating user attributes. Koppla safely wraps AD operations behind an AI-friendly interface, with a configurable write-enabled mode to prevent unintended changes. The included configuration manager helps securely store credentials and propagate settings to Claude Desktop so your MCP-enabled assistant can interact with AD in a structured way.

To use Koppla, connect your MCP-enabled agent to the Koppla server entry (e.g., Koppla-Active-Directory) in Claude Desktop's mcpServers configuration. Initiate a session and start issuing natural language prompts such as: "Find all inactive users who haven't logged in for 90 days", "Add Jane Doe to the IT Admins group", or "Show me all groups without members". Koppla translates these requests into LDAP queries and write operations (when enabled), performing the appropriate AD actions while enforcing security protections and write restrictions as configured. If you need to validate a connection or inspect the current configuration, you can use Koppla's configuration tools prior to or during a session.

Prerequisites:

• Python 3.7 or higher
• Access to an Active Directory environment
• Network connectivity between the Koppla server and AD domain controller

1. Install Koppla

• Install the Koppla package from PyPI:

pip install koppla

2. Run Koppla locally (example)

• Start the Koppla server module which exposes the MCP endpoint "koppla.server":

python -m koppla.server

• If you need to customize the configuration, create a configuration file or set environment variables as shown in the manual configuration example below.

3. Optional: Configure via Claude Desktop (recommended)

• Create or update Claude Desktop configuration (claude_desktop_config.json) to point to Koppla:

{
  "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=example,DC=com",
        "AD_WRITE_ENABLED": "false"
      }
    }
  }
}

4. Optional: Test configuration

• Use Koppla's configuration manager to securely store credentials and test the AD connection (see Koppla documentation for exact commands).

5. Verify prerequisites are met and run the MCP server as described above.

Tips and considerations:

• Environment variables AD_SERVER, AD_USER, AD_PASSWORD, BASE_DN, and AD_WRITE_ENABLED control how Koppla connects to AD and whether it can perform write operations. Keep AD_PASSWORD secure and consider enabling AD_WRITE_ENABLED only when you trust the agent.
• Koppla uses Fernet encryption for stored passwords when using the configuration manager; passwords are not stored in plain text in configuration files.
• By default, write operations are disabled to prevent unintended changes. When enabling writes, ensure administrators approve actions and consider implementing role-based access controls with Claude Desktop prompts.
• Always test AD connectivity with koppla-config test or equivalent before enabling production writes.
• Be mindful of data processing and privacy: some prompts may involve sending AD data to external AI models. Ensure compliance with your organization’s data handling policies.
• Regular backups of Claude Desktop configuration are created automatically before changes, with timestamps for easy restoration.