LDAP Assistant MCP

LDAP Assistant MCP

Beta — 只读的 389 Directory Server 诊断，适用于评估和内部故障排查。工具架构、输出格式和配置字段在 1.0.0 发布前仍可能变更。

LDAP Assistant MCP 可将你的 AI 助手变成 389 Directory Server 支持工程师。 将它连接到运行中的服务、已停止的实例，或客户案例中的 SOS 报告，然后询问：

• “我的目录服务出了什么问题？”
• “在我创建案例之前，先总结一下这份 SOS 报告。”
• “这些服务之间的复制似乎出了问题——为什么？”

它通过基于 lib389（官方 389 DS 管理库）构建的 42 个只读诊断工具，给出按优先级排列的发现结果（严重性、影响、修复措施）。隐私模式默认开启：在任何内容传给大模型之前，DN、主机名和 IP 地址都会被隐藏。

支持的提供程序：389 Directory Server。（OpenLDAP 提供程序代码目前仅供实验使用，需通过选择加入标志启用，不提供隐私保证，也不在支持协议范围内——参见环境变量。）

安装

前提条件

• Linux（主要支持）或 macOS。原生不支持 Windows（python-ldap 没有官方 Windows wheel）——请使用 WSL2（参见安装操作手册）

• Python 3.11+（CI 测试使用 3.13）

• uv 包管理器

• MCP 客户端（Claude Desktop、Claude Code、Cursor、Gemini CLI 等）

• 系统开发库（构建 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"
  

安装过程中遇到问题？→ 安装故障排查操作手册

从 PyPI 安装（推荐）

无需克隆——MCP 客户端会通过 uvx 运行已发布的软件包。请先跳转到配置服务，然后使用以下客户端配置（Claude Desktop：macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

LDAP_SERVERS_CONFIG 请使用绝对路径——相对路径会相对于 MCP 客户端的工作目录解析，而该目录通常并非你以为的位置。

从源代码安装（开发）

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

然后，在生成的客户端条目中按上文所述设置 LDAP_SERVERS_CONFIG。关于测试容器和架构，请参见开发指南。

配置你的服务

创建一个 servers.json，其中包含你的 LDAP 服务。**注意：**隐私模式下不会隐藏 name 字段——该字段会原样传给 AI Agent，以便它们在多次工具调用中引用服务。请勿在服务名称中填写主机名、IP 地址或其他私人信息。

{
  "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"
    }
  ]
}

注意：serverid 是实例名称中不带 slapd- 前缀的部分（例如，实例 slapd-localhost 的 serverid 为 localhost）。

四种服务器模式

模式	配置	可用功能
远程	仅 ldap_url	通过 LDAP 使用健康状况、复制、性能、配置和条目工具。不支持访问日志、磁盘或证书
本地	+ is_local: true、serverid	包含上述所有功能，此外还支持日志分析、磁盘监控、证书检查和进程指标
离线	+ is_offline: true	分析已停止的本地实例，读取 dse.ldif 和日志文件——无需 LDAP 连接。适用于事后分析，以及无法启动的实例
存档	is_archive: true、archive_path	分析来自任意机器的 SOS 报告或配置／日志摘录（tarball 或目录，自动检测布局）。无需 LDAP，也无需本地实例

需要实时连接的工具会明确说明——错误信息会列出在该服务器模式下可用的工具，让调查得以继续，而不会陷入死胡同。

远程 LDAPS 证书验证： 默认情况下，远程 ldaps:// 服务器会验证服务器证书（"tls_verify": true；基于环境变量的配置则使用 LDAP_TLS_VERIFY 环境变量）。若要连接使用自签名或其他不受信任证书的服务器，请在该服务器条目中设置 "tls_verify": false——这会完全停用证书验证，因此仅在可信的实验环境中使用。

编辑客户端配置或 servers.json 后，重启 MCP 客户端，然后验证：询问 “配置了哪些 LDAP 服务器？”

隐私模式

默认情况下，隐私模式已启用——工具输出中的敏感数据（DN、主机名、IP、用户详细信息）会被脱敏。可访问单个条目的工具（get_user_details、ldap_search）会被禁用；列表工具仅返回计数。诊断指标（计数、比率、百分比）仍然可见。

若要在仅限可信环境中启用完整数据访问：

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

重要提示： 仅在使用本地模型、私有云大模型实例，或处理测试／示例数据时启用此功能。连接到生产目录时，请避免在使用公共大模型的情况下启用——你的目录信息可能会被纳入其训练数据或日志。

启用隐私模式时（默认）：

• 主机名、DN、IP 地址和后缀会被匿名化
• 配置值会被隐藏
• 敏感工具会被禁用
• 诊断指标（计数、比率、百分比）仍然可见
• 服务器名称（servers.json 中的 name 字段）绝不会被脱敏——这是用户选择的标签，在不同工具调用间必须保持稳定。请勿在服务器名称中填写主机名、IP 或其他私人信息。

数据处理

• 不收集遥测数据。 服务不会收集任何信息，也不会向外发送数据。
• 所有操作都在本地运行。 目录数据从 LDAP 服务器、本地实例或存档文件中读取，并且只返回给 MCP 客户端——客户端会将工具结果转发给你配置的大模型。隐私模式（默认开启）会在敏感值离开服务进程前将其脱敏。
• 凭据保存在本地的 servers.json／环境变量中；它们绝不会出现在工具输出中，工具错误信息也会经过清理。

首先要问的问题

你想要	提问 / 使用	背后的工具
查看所有内容的健康状况概览	“我的目录服务有什么问题？”	first_look
获取摘要版 SOS 报告	“分析 sos-report 存档” 或 archive_investigation 提示词	analyze_archive → 存档操作手册
了解哪个工具适合某个目标	tool_navigator 提示词	针对指定目标的工具映射
按引导排查复制问题	diagnose_replication 提示词	复制工具调用顺序
按引导排查性能问题	performance_investigation 提示词	性能工具调用顺序
进行晨间运维检查	daily_health_check 提示词	健康状况 + 监控巡查

操作手册（症状 → 工具 → 工具无法获知的内容 → 手动验证方法）：

• 打开案例前先总结 SOS 报告
• 安装故障排查

按组划分的工具

42 个只读工具——包含参数的完整参考，请参阅 TOOLS.md。

组	工具	重点
健康状况	first_look、run_healthcheck、list_healthchecks、server_health	多服务概览；完整的 dsctl healthcheck 等效功能
复制	get_replication_status、get_replication_topology、check_replication_lag、list_replication_conflicts、get_agreement_status	RUV/CSN 分析、拓扑映射、冲突条目
性能	get_performance_summary、缓存/连接/操作/线程/资源统计	瓶颈检测和调优建议
索引	list_indexes、analyze_index_configuration、find_unindexed_searches	基于访问日志查找未使用索引的搜索
配置	get_server_configuration、compare_server_configurations、list_plugins、get_backend_configuration	实时和离线（dse.ldif）路径
日志	analyze_access_log / analyze_error_log / analyze_audit_log（统计信息，保护隐私），parse_*_log（完整条目，需要敏感数据模式）	传统和 JSON 日志格式
存档 / SOS	analyze_archive、validate_configuration、compare_dse_configs	清单、离线配置检查、完整 dse.ldif 差异比较
用户和组	列出/搜索/检查用户，筛选活跃/锁定用户，查看组	隐私模式下仅显示数量
高级	ldap_search、run_monitor、list_servers、cn=config 资源	通用搜索（仅限敏感数据模式）

环境变量参考

变量	默认值	用途
LDAP_SERVERS_CONFIG	–	servers.json 的绝对路径（多服务配置；优先使用）
LDAP_PROVIDER	dirsrv	服务实现。目前仅支持 dirsrv（389 DS）；openldap 需要通过下方标志选择启用
LDAP_MCP_EXPERIMENTAL_OPENLDAP	false	选择启用实验性的 OpenLDAP 提供程序（两个工具，不保证隐私）
LDAP_MCP_EXPOSE_SENSITIVE_DATA	false	禁用隐私模式（参见隐私模式）
LDAP_MCP_DEBUG	false	在工具错误中启用调试日志和回溯信息
LDAP_MCP_TOOL_TIMEOUT	30	每次工具调用的超时时间（秒）
LDAP_MCP_MAX_TOOL_TIMEOUT	120	耗时较长的工具（first_look、归档比较等）的超时上限
LDAP_CONNECT_TIMEOUT	30	LDAP 网络/操作超时时间（秒），防止连接不可达的服务时卡住

单服务回退配置（仅在未设置 LDAP_SERVERS_CONFIG 时使用）：

变量	默认值	用途
LDAP_URL	–	完整的 LDAP URL（可替代主机名/端口/SSL 变量）
LDAP_HOSTNAME / LDAP_PORT / LDAP_USE_SSL	localhost / 389 / false	连接参数
LDAP_BASE_DN	–	默认搜索基准
LDAP_BIND_DN / LDAP_BIND_PASSWORD	cn=Directory Manager / –	绑定凭据（无默认密码）
LDAP_AUTH_METHOD	simple	simple 或 anonymous（唯一已实现的绑定方式；LDAPI/SASL EXTERNAL 通过 LDAP_USE_LDAPI 选择，而非在此处设置）
LDAP_IS_LOCAL / LDAP_SERVERID	false / –	启用本地实例功能（日志、磁盘、证书）
LDAP_USE_LDAPI	false	通过 LDAPI Unix 套接字连接
LDAP_IS_OFFLINE	false	将本地实例视为已停止（离线模式）
LDAP_TLS_VERIFY	true	验证远程 ldaps:// 连接的服务证书（仅在可信实验环境中设为 false）

故障排除

问题	原因 / 解决方法
安装期间 python-ldap 构建失败	缺少系统头文件——参见安装操作指南
工具报告默认的 localhost 服务，而不是你的配置	未设置 LDAP_SERVERS_CONFIG，或无法在 MCP 客户端配置中加载——参见 servers.json 路径解析
list_* 工具仅返回计数；ldap_search/get_user_details 拒绝运行	这是隐私模式（默认设置，符合预期）——参见隐私模式
出现“requires a running server with a live LDAP connection”错误	目标是离线/归档服务——错误消息会列出可在该服务上运行的工具
本地服务的 LDAPI 连接失败	检查 serverid 是否不含 slapd- 前缀，以及实例套接字是否存在

没有可供测试的 LDAP 服务？开发指南会使用 Docker 启动测试容器。

限制

• Beta 版——工具架构、输出格式和配置字段在 1.0.0 之前可能会发生变化
• 大模型解读——工具会返回准确的数据，但由大模型进行解读，因此可能出现幻觉。采取行动前，请务必核实建议。
• 只读——暂不支持写入操作
• 明文密码——请对配置文件使用严格的文件权限
• 仅支持 STDIO 传输——暂不支持 HTTP/SSE

文档

文档	说明
更新日志	版本历史和发行说明
归档 / SOS 操作手册	开启工单前总结 SOS 报告
安装操作手册	python-ldap 构建、WSL2、uvx、配置路径解析
开发指南	开发环境设置、配置、架构
测试指南	运行和编写测试
贡献指南	如何参与贡献
发行检查清单	如何制作和验证发行版本
389 DS 工具	389 Directory Server 工具参考
OpenLDAP 工具	OpenLDAP 工具参考（实验性，仅限选择启用）

许可证

GPL-3.0-or-later。基于 lib389（官方 389 Directory Server 管理库）和 FastMCP 构建。

参考资料

• PyPI 软件包
• 官方 MCP 注册表 — 登记名称为 io.github.droideck/ldap-assistant-mcp
• Model Context Protocol
• 389 Directory Server
• FastMCP 2.0