LDAP Assistant MCP

Beta — read-only 389 Directory Server diagnostics, suitable for evaluation and internal troubleshooting. Tool schemas, output formats, and configuration fields may still change before 1.0.0.

LDAP Assistant MCP turns your AI assistant into a 389 Directory Server support engineer. Point it at live servers, stopped instances, or an SOS report from a customer case, and ask:

• "What's wrong with my directory servers?"

• "Summarize this SOS report before I open the case."

• "Replication looks broken between these servers — why?"

It answers with prioritized findings (severity, impact, remediation) from 42 read-only diagnostic tools built on lib389, the official 389 DS administration library. Privacy mode is on by default: DNs, hostnames, and IPs are redacted before anything reaches the LLM.

Supported provider: 389 Directory Server. (OpenLDAP provider code exists experimentally behind an opt-in flag, with no privacy guarantees, and is not part of the support contract — see Environment Variables.)

Install

Prerequisites

• Linux (primary) or macOS. Windows is not supported natively (python-ldap has no official Windows wheels) — use WSL2 (see the install playbook)

• Python 3.11+ (3.13 is what CI tests against)

• uv package manager

• MCP client (Claude Desktop, Claude Code, Cursor, Gemini CLI, etc.)

• System development libraries (needed to build python-ldap):

  Fedora / RHEL / CentOS:

  sudo dnf install python3-devel openldap-devel cyrus-sasl-devel openssl-devel gcc

  Ubuntu / Debian:

  sudo apt install python3-dev libldap2-dev libsasl2-dev libssl-dev gcc

  macOS (Homebrew):

  brew install openldap
  export LDFLAGS="-L$(brew --prefix openldap)/lib"
  export CPPFLAGS="-I$(brew --prefix openldap)/include"

Anything failing during install? → Installation troubleshooting playbook

From PyPI (recommended)

No clone needed — your MCP client runs the published package via uvx. Skip ahead to Configure your servers, then use this client configuration (Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ldap-assistant-mcp": {
      "command": "uvx",
      "args": ["ldap-assistant-mcp"],
      "env": {
        "LDAP_SERVERS_CONFIG": "/absolute/path/to/servers.json"
      }
    }
  }
}

Use an absolute path for LDAP_SERVERS_CONFIG — relative paths resolve against the MCP client's working directory, which is usually not where you think.

From source (development)

git clone https://github.com/droideck/ldap-assistant-mcp.git
cd ldap-assistant-mcp
uv venv && source .venv/bin/activate
uv pip install -e .[dev]

# Register with your MCP client via FastMCP:
fastmcp install claude-desktop fastmcp.json   # or: fastmcp install claude-code fastmcp.json

Then set LDAP_SERVERS_CONFIG in the generated client entry as above. See the Development Guide for test containers and architecture.

Related MCP server: mcp-activedirectory

Configure your servers

Create a servers.json with your LDAP server(s). Note: the name field is never redacted in privacy mode — it is passed as-is to AI agents so they can reference servers across tool calls. Do not put hostnames, IPs, or other private information in server names.

{
  "servers": [
    {
      "name": "local-ds",
      "ldap_url": "ldap://localhost:389",
      "base_dn": "dc=example,dc=com",
      "bind_dn": "cn=Directory Manager",
      "bind_password": "your-password",
      "provider_type": "389ds",
      "is_local": true,
      "serverid": "localhost"
    },
    {
      "name": "remote-ds",
      "ldap_url": "ldap://ldap.example.com:389",
      "base_dn": "dc=example,dc=com",
      "bind_dn": "cn=Directory Manager",
      "bind_password": "your-password",
      "provider_type": "389ds"
    },
    {
      "name": "stopped-ds",
      "ldap_url": "ldap://localhost:389",
      "base_dn": "dc=example,dc=com",
      "bind_dn": "cn=Directory Manager",
      "bind_password": "unused-in-offline-mode",
      "provider_type": "389ds",
      "is_local": true,
      "serverid": "localhost",
      "is_offline": true
    },
    {
      "name": "sos-report",
      "provider_type": "389ds",
      "is_archive": true,
      "archive_path": "/path/to/sosreport-host-2025/",
      "instance_name": "slapd-instance"
    }
  ]
}

Note: serverid is the instance name without the slapd- prefix (e.g. localhost for the instance slapd-localhost).

The four server modes

Tools that need a live connection tell you so — the error names the tools that do work in that server's mode, so the investigation continues instead of dead-ending.

Remote LDAPS certificate verification: remote ldaps:// servers verify the server certificate by default ("tls_verify": true, or the LDAP_TLS_VERIFY environment variable for env-based config). To connect to a server with a self-signed or otherwise untrusted certificate, set "tls_verify": false on that server entry — this disables certificate verification entirely, so use it only for trusted lab environments. Local instances (is_local: true) instead use the instance's own NSS certificate directory.

After editing the client config or servers.json, restart your MCP client, then verify: ask "Which LDAP servers are configured?"

Privacy mode

By default, privacy mode is enabled — sensitive data (DNs, hostnames, IPs, user details) is redacted from tool outputs. Tools that expose individual entries (get_user_details, ldap_search) are disabled; list tools return counts only. Diagnostic metrics (counts, ratios, percentages) remain visible.

To enable full data access in trusted environments only:

{
  "env": {
    "LDAP_MCP_EXPOSE_SENSITIVE_DATA": "true"
  }
}

Important: Only enable this with local models, private cloud LLM instances, or when working with test/sample data. Avoid enabling with public LLMs when connected to production directories — your directory information could be included in their training data or logs.

When privacy mode is enabled (default):

• Hostnames, DNs, IP addresses, and suffixes are anonymized

• Configuration values are redacted

• Sensitive tools are disabled

• Diagnostic metrics (counts, ratios, percentages) remain visible

• Server names (the name field in servers.json) are never redacted — they are user-chosen labels that must remain stable across tool calls. Do not put hostnames, IPs, or other private information in server names.

Data handling

• No telemetry. The server collects nothing and phones home to no one.

• Everything runs locally. Directory data is read from your LDAP servers, local instances, or archive files and returned only to your MCP client — which forwards tool results to whatever LLM you have configured. Privacy mode (on by default) redacts sensitive values before they leave the server process.

• Credentials stay in your local servers.json / environment variables; they are never included in tool output and tool errors are sanitized.

First questions to ask

Playbooks (symptom → tools → what they can't know → how to verify by hand):

• Summarize an SOS report before opening the case

• Installation troubleshooting

Tools by group

42 read-only tools — full reference with parameters in TOOLS.md.

Environment Variable Reference

Single-server fallback (used only when LDAP_SERVERS_CONFIG is not set):

Troubleshooting

No LDAP server to test against? The Development Guide spins up test containers with Docker.

Limitations

• Beta — Tool schemas, output formats, and configuration fields may change before 1.0.0

• LLM interpretation — Tools return accurate data, but the LLM interprets it. Hallucinations are possible. Always verify recommendations before acting.

• Read-only — No write operations yet

• Plain text passwords — Use restrictive file permissions on config files

• STDIO transport only — No HTTP/SSE support yet

Documentation

License

GPL-3.0-or-later. Built on lib389 (the official 389 Directory Server administration library) and FastMCP.

References

• PyPI package

• Official MCP Registry — listed as io.github.droideck/ldap-assistant-mcp

• Model Context Protocol

• 389 Directory Server

• FastMCP 2.0