Kanidm MCP Server (mcp-kanidm)

A professional Model Context Protocol (MCP) server for managing an advanced Kanidm deployment. Built completely asynchronously leveraging httpx and FastMCP.

This server is designed to work via the Kanidm REST v1 API using Service Accounts to keep your intelligent agents sandboxed and robust (eliminating standard CLI shell constraints).

Features

Provides the following MCP tools for Identity and Access Management in Kanidm:

• list_users: Queries validated user identities with simple search filters.
• get_user_details: Extends deep query capabilities into PII attributes and precise access windows (requires an appropriate service account assigned).
• reset_password_intent: Generates a credential update intent token for help-desking scenarios securely (the AI agent will never directly reset nor touch user passwords directly).
• delete_user: Manages robust termination via a Human-in-the-Loop (HITL) prompt (ctx.elicit()) guaranteeing a person grants affirmative consent ahead of any destructive REST operation.

Installation and Usage

To install or run this server dynamically within any compatible framework (Claude Desktop, etc.), you can run it via uvx dynamically or install via Python global packages using uv.

Autenticación: Cómo obtener el KANIDM_TOKEN

Importante: Nunca debes configurar el agente MCP utilizando tu cuenta principal de admin. Para mantener la seguridad, aislar los privilegios y garantizar un rastro de auditoría claro, debes usar una Cuenta de Servicio (Service Account).

Sigue estos 3 pasos usando la CLI de Kanidm:

1. Crear una cuenta de servicio para esta integración (por ejemplo, llamada mcp-agent):

   kanidm service-account create mcp-agent "MCP Server Agent"
   

2. Asignarle los privilegios correctos. Añade esta cuenta al grupo adecuado, como idm_people_admins (para gestión completa de usuarios) o idm_service_desk (para tareas de soporte):

   kanidm group add-members idm_people_admins mcp-agent
   

3. Generar un API Token:

   kanidm service-account api-token generate mcp-agent --name mcp-token
   

El comando te devolverá una larga cadena. Ese es tu KANIDM_TOKEN.

Execution Environment

To authenticate safely against Kanidm instances, configure your agent to inject these environmental variables securely:

• KANIDM_URL: Base URI of the target Kanidm system (e.g. https://kanidm.mydomain.local)
• KANIDM_TOKEN: The API Token generated for your Service Account in the previous step.

Configuring the Agent (e.g. Claude Desktop)

In your claude_desktop_config.json:

{
  "mcpServers": {
    "kanidm-server": {
      "command": "uvx",
      "args": [
        "mcp-kanidm"
      ],
      "env": {
        "KANIDM_URL": "https://idm.company.private",
        "KANIDM_TOKEN": "YOUR-SERVICE-ACCOUNT-TOKEN"
      }
    }
  }
}

Note: For testing inside enterprise proxies with strict self-signed cert blocks, run the uv instances with the necessary proxy fallback arguments (--allow-insecure-host=...).

Local Development

1. Run uv sync --all-groups to install code, documentation tools, and dev dependencies fully.
2. Initialize pre-commits to automatically check your code syntax before commits: uv run pre-commit install
3. Run uv run mcp-kanidm to launch the STDIO pipeline manually.

Note: For testing inside enterprise proxies with strict self-signed cert blocks, run the uv instances with the necessary proxy fallback arguments (--allow-insecure-host=files.pythonhosted.org --allow-insecure-host=pypi.org).