LDAP Assistant MCP

LDAP Assistant MCP

ベータ版 — 読み取り専用の 389 Directory Server 診断機能です。評価や社内でのトラブルシューティングに適しています。ツールのスキーマ、出力形式、設定フィールドは、1.0.0 より前に変更される可能性があります。

LDAP Assistant MCP は、AI アシスタントを 389 Directory Server のサポートエンジニアに変えます。 稼働中のサーバー、停止中のインスタンス、または顧客案件の SOS レポートを指定して、次のように質問できます。

• 「ディレクトリサーバーに何か問題がありますか？」
• 「案件を開始する前に、この SOS レポートを要約してください。」
• 「これらのサーバー間でレプリケーションが壊れているようです。なぜですか？」

lib389（公式の 389 DS 管理ライブラリ）を基盤とする 42 個の読み取り専用診断ツールから、優先順位付けされた調査結果（重大度、影響、修正方法）を返します。プライバシーモードはデフォルトで有効で、LLM に渡される前に DN、ホスト名、IP アドレスがマスキングされます。

サポート対象のプロバイダー：389 Directory Server。（OpenLDAP プロバイダーのコードは、オプトインフラグで実験的に利用できますが、プライバシーは保証されず、サポート契約の対象外です。詳しくは環境変数を参照してください。）

インストール

前提条件

• Linux（主な対象）または macOS。Windows はネイティブではサポートされていません（python-ldap の公式 Windows ホイールがないため）。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 を設定してください。テスト用コンテナとアーキテクチャについては、開発ガイドを参照してください。

サーバーの設定

LDAP サーバーを登録した servers.json を作成します。注： name フィールドはプライバシーモードでもマスキングされません。ツール呼び出しをまたいでサーバーを識別できるよう、そのまま AI エージェントに渡されます。サーバー名にホスト名、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 の場合は localhost）。

4 つのサーバーモード

モード	設定	利用できる機能
リモート	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 を設定します。これにより証明書の検証が完全に無効になるため、信頼できるラボ環境でのみ使用してください。ローカルインスタンス（is_local: true）では、代わりにインスタンス独自の NSS 証明書ディレクトリを使用します。

クライアント設定または servers.json を編集したら、MCP クライアントを再起動してから、「どの LDAP サーバーが設定されていますか？」 と尋ねて確認してください。

プライバシーモード

デフォルトでは、プライバシーモードが有効になっており、ツールの出力から機密データ（DN、ホスト名、IP、ユーザーの詳細情報）がマスキングされます。個別のエントリーを公開するツール（get_user_details、ldap_search）は無効になり、一覧表示ツールは件数のみを返します。診断メトリクス（件数、比率、パーセンテージ）は引き続き表示されます。

信頼できる環境でのみ、すべてのデータへのアクセスを有効にするには：

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

重要： ローカルモデル、プライベートクラウドの LLM インスタンスを使用する場合、またはテスト／サンプルデータを扱う場合にのみ有効にしてください。本番ディレクトリに接続している状態で公開 LLM を使用する場合は、有効にしないでください。ディレクトリ情報が、それらのトレーニングデータやログに含まれる可能性があります。

プライバシーモードが有効な場合（デフォルト）：

• ホスト名、DN、IP アドレス、サフィックスは匿名化されます
• 設定値はマスキングされます
• 機密情報を扱うツールは無効になります
• 診断メトリクス（件数、比率、パーセンテージ）は引き続き表示されます
• サーバー名（servers.json の name フィールド）は決してマスキングされません。ユーザーが選択するラベルであり、ツール呼び出し間で一貫性を保つ必要があります。サーバー名にホスト名、IP、その他の個人情報を含めないでください。

データの取り扱い

• テレメトリーはありません。 サーバーは何も収集せず、外部に情報を送信することもありません。
• すべてローカルで実行されます。 ディレクトリデータは LDAP サーバー、ローカルインスタンス、またはアーカイブファイルから読み取られ、MCP クライアントにのみ返されます。MCP クライアントは、ツールの結果を設定済みの任意の LLM に転送します。デフォルトで有効なプライバシーモードにより、機密値はサーバープロセスの外部に出る前にマスキングされます。
• 認証情報はローカルの servers.json／環境変数に保持されます。ツールの出力に含まれることはなく、ツールのエラーもサニタイズされます。

最初に確認すること

目的	質問する／使用する	裏側で実行されるもの
すべてのサーバーの健全性を把握する	「ディレクトリーサーバーに問題はありますか？」	first_look
SOS レポートを要約する	「SOS レポートのアーカイブを分析して」 または 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 プロバイダーをオプトインします（2 つのツールを提供。プライバシーの保証はありません）
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 でテスト用コンテナーを起動できます。

制限事項

• ベータ版 — ツールのスキーマ、出力形式、設定フィールドは 1.0.0 より前に変更される場合があります
• LLM による解釈 — ツールは正確なデータを返しますが、その解釈は LLM が行います。幻覚が生じる可能性があります。推奨事項に従って行動する前に、必ず確認してください。
• 読み取り専用 — 書き込み操作はまだありません
• プレーンテキストのパスワード — 設定ファイルのアクセス権を制限してください
• 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 Registry — io.github.droideck/ldap-assistant-mcp として登録されています
• Model Context Protocol
• 389 Directory Server
• FastMCP 2.0