Servidor KSM MCP - Acceso seguro de IA a los secretos de Keeper

KSM MCP es un servidor del Protocolo de Contexto de Modelo (MCP) que actúa como un intermediario seguro entre los modelos de lenguaje de IA (como Claude) y Keeper Secrets Manager (KSM). Permite a los agentes de IA gestionar tus secretos de KSM, como listar, crear, recuperar y eliminar registros y carpetas, mientras protege las credenciales de tu aplicación KSM. Las operaciones sensibles requieren confirmación del usuario, lo que garantiza que mantengas el control sobre tus datos.

Guía rápida para el usuario

Opción 1: Usar Docker (Recomendado)

1. Obtén la configuración KSM en Base64:

   • Inicia sesión en Keeper Secrets Vault.

   • Navega a tu Secrets Manager, Aplicación y luego a la pestaña "Devices" (Dispositivos).

   • Haz clic en "Add Device" (Añadir dispositivo) y copia la cadena de configuración codificada en base64 proporcionada (normalmente empieza por ewog...).

   Importante: La configuración en base64 contiene las credenciales de tu aplicación KSM. Mantenla segura y nunca la subas a un control de versiones.

2. Configura Claude Desktop:

   • Abre tu archivo de configuración de Claude Desktop:

     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

     • Windows: %APPDATA%\Claude\claude_desktop_config.json

     • Linux: ~/.config/Claude/claude_desktop_config.json

   • Añade o actualiza la entrada del servidor ksm de la siguiente manera, reemplazando YOUR_BASE64_CONFIG_STRING_HERE con tu configuración real en base64:

   {
     "mcpServers": {
       "ksm": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING_HERE",
           "keeper/keeper-mcp-server:latest"
         ]
       }
       // You might have other servers like "memory" here, leave them as is.
     }
   }

3. Reinicia Claude Desktop:

   • El servidor KSM debería estar ahora disponible para Claude. La primera vez que se conecte, utilizará la configuración en base64 para iniciarse.

Opción 2: Usar un binario precompilado

1. Descarga el binario:

   • Ve a la página de lanzamientos de KSM MCP y descarga el binario adecuado para tu sistema operativo (por ejemplo, ksm-mcp-darwin-amd64 para Macs con Intel, ksm-mcp-windows-amd64.exe para Windows).

   • Haz que el binario sea ejecutable (por ejemplo, chmod +x ./ksm-mcp-darwin-amd64) y colócalo en un directorio incluido en el PATH de tu sistema, o anota su ruta completa.

2. Obtén la configuración KSM en Base64: (Consulta el paso 1 en la guía de Docker anterior)

   Importante: La configuración en base64 contiene las credenciales de tu aplicación KSM. Mantenla segura y nunca la subas a un control de versiones.

3. Inicializa el perfil de KSM MCP:

   • Abre tu terminal y ejecuta el comando de inicialización, reemplazando YOUR_BASE64_CONFIG_STRING y eligiendo un nombre de perfil (por ejemplo, default):

     /path/to/ksm-mcp init --profile default --config "YOUR_BASE64_CONFIG_STRING"

   • Se te pedirá que establezcas una contraseña de protección para tu almacén de perfiles local. Recuerda esta contraseña, ya que la necesitarás si reinicias el servidor manualmente o si está configurado para requerirla. Para el uso automatizado con Claude, a menudo el servidor se ejecuta en modo por lotes donde no se solicita de forma interactiva.

4. Configura Claude Desktop:

   • Abre tu archivo claude_desktop_config.json (consulta las rutas en la guía de Docker).

   • Añade o actualiza la entrada del servidor ksm, reemplazando /path/to/ksm-mcp con la ruta real a tu binario descargado: GXP3

5. Reinicia Claude Desktop.

Related MCP server: keyshade-mcp

Capacidades (Herramientas disponibles)

El servidor KSM MCP proporciona las siguientes herramientas para interactuar con Keeper Secrets Manager:

Operaciones con secretos

• list_secrets: Lista todos los secretos accesibles (solo metadatos).

• get_secret: Recupera un secreto específico (los campos sensibles están enmascarados por defecto; desenmascararlos requiere confirmación).

• search_secrets: Busca secretos por título, notas u otro contenido de campo.

• create_secret: Crea un nuevo secreto (requiere confirmación).

• update_secret: Actualiza un secreto existente (requiere confirmación).

• delete_secret: Elimina un secreto (requiere confirmación).

Operaciones con carpetas

• list_folders: Lista todas las carpetas accesibles.

• create_folder: Crea una nueva carpeta (requiere confirmación; debe especificar una carpeta compartida principal).

• delete_folder: Elimina una carpeta (requiere confirmación; opción para forzar la eliminación de carpetas no vacías).

Gestión de archivos (dentro de los secretos)

• upload_file: Sube un archivo adjunto a un secreto (requiere confirmación).

• download_file: Descarga un archivo adjunto de un secreto.

Utilidades

• generate_password: Genera una contraseña segura. Opcionalmente, puede guardarla directamente en un nuevo secreto sin exponerla a la IA.

• get_totp_code: Obtiene el código TOTP actual para un secreto que tenga TOTP configurado.

• get_server_version: Obtiene la versión actual del servidor KSM MCP.

• health_check: Comprueba el estado operativo del servidor MCP y su conexión con KSM.

Casos de uso de ejemplo

Aquí tienes algunos ejemplos de cómo podrías indicar a un agente de IA (como Claude) que utilice el servidor KSM MCP:

• Crear un nuevo secreto en una nueva carpeta: "Por favor, crea una nueva carpeta llamada 'Project Phoenix Shared' bajo nuestra carpeta compartida principal 'KSM-MCP-TEST-RECORDS'. Luego, dentro de 'Project Phoenix Shared', crea un nuevo secreto de inicio de sesión titulado 'Phoenix Dev DB' con el nombre de usuario 'phoenix_user', la contraseña 'ComplexP@$$wOrd123!' y la URL 'db.phoenix.dev.internal'."

• Listar secretos y recuperar uno: "Lista todos los secretos en la carpeta 'API Keys'. Luego, obtén los detalles del secreto titulado 'Third-Party Analytics API Key', pero mantén la clave API enmascarada."

• Eliminar un secreto y luego su carpeta (si está vacía): "Elimina el secreto llamado 'Old Staging Server Credentials'. Una vez hecho esto, si la carpeta 'Staging Environment' en la que estaba ahora está vacía, por favor elimina esa carpeta también."

• Subir un archivo de configuración a un registro existente: "Tengo un nuevo archivo de configuración de Kubernetes para nuestro clúster de producción en '~/Downloads/kubeconfig-prod.yaml'. Por favor, sube este archivo al registro de KSM titulado 'Production K8s Cluster Access' y nombra el archivo adjunto 'kubeconfig-prod-cluster.yaml'."

• Generar una contraseña segura y guardarla en un nuevo registro: "Genera una contraseña muy fuerte de 32 caracteres con mayúsculas, minúsculas, números y caracteres especiales. Guárdala directamente en un nuevo registro de inicio de sesión titulado 'Internal Audit Service Account' en la carpeta 'Service Accounts'. No me muestres la contraseña."

• Comprobar la consistencia de la configuración entre entornos: "Tengo registros de configuración de servicios organizados en carpetas por entorno (dev, qa) con subcarpetas para cada región de AWS. Por favor, analiza estos registros e identifica cualquier inconsistencia entre servicios similares en diferentes entornos. Presta especial atención a los valores de configuración que normalmente deberían ser iguales en todos los entornos, como los niveles de registro, los ajustes de tiempo de espera o las banderas de características."

Referencia de configuración del servidor

El servidor KSM MCP puede instanciarse de múltiples formas con varias opciones de configuración. Esta sección documenta todos los métodos, banderas y variables de entorno disponibles.

Métodos de configuración

Método 1: Docker con variables de entorno (Recomendado)

{
  "mcpServers": {
    "ksm": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING",
        "keeper-mcp-server:latest"
      ]
    }
  }
}

Método 2: Binario precompilado con perfil

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve", "--profile", "default"]
    }
  }
}

Método 3: Binario precompilado con configuración Base64 (Bandera CLI)

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

Método 4: Binario precompilado con variables de entorno

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve"],
      "env": {
        "KSM_CONFIG_BASE64": "YOUR_BASE64_CONFIG_STRING"
      }
    }
  }
}

Método 5: Modo silencioso (Sin registros locales)

Para entornos donde deseas evitar cualquier creación de archivos locales (incluidos los registros de auditoría):

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--no-logs",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

La bandera --no-logs deshabilita completamente el registro de auditoría, asegurando que no se creen archivos locales. Esto es útil para:

• Entornos de cumplimiento donde se debe evitar la creación de archivos locales

• Despliegues en contenedores donde no se desea persistencia

• Escenarios temporales o de prueba

• Sistemas con sistemas de archivos de solo lectura

Banderas de línea de comandos

Detalles de las banderas

--batch (Modo no interactivo)

• Propósito: Evita que el servidor solicite contraseñas o entrada del usuario

• Cuándo usarlo:

  • Entornos automatizados (CI/CD, contenedores Docker)

  • Cuando se ejecuta como un servicio donde no es posible la interacción humana

  • Integración con Claude Desktop (recomendado)

• Qué hace:

  • Omite las solicitudes de contraseña al cargar perfiles cifrados

  • Utiliza variables de entorno o banderas CLI para toda la configuración

  • Falla correctamente si falta la entrada requerida en lugar de bloquearse

--no-logs (Modo silencioso)

• Propósito: Deshabilita completamente el registro de auditoría para evitar cualquier creación de archivos locales

• Cuándo usarlo:

  • Entornos de cumplimiento donde se deben evitar los artefactos locales

  • Despliegues en contenedores o efímeros

  • Entornos de sistema de archivos de solo lectura

  • Escenarios de prueba donde la limpieza es importante

• Qué hace:

  • Evita la creación del directorio ~/.keeper/ksm-mcp/logs/

  • Deshabilita todo el registro de auditoría (registros de acceso, registros de errores, registros del sistema)

  • Mantiene la funcionalidad completa de MCP sin sobrecarga de registro

  • Operación segura con envoltorios de verificación nula para todas las llamadas de registro

• Seguridad: Alta - no se escriben datos sensibles en archivos locales

--auto-approve (Peligroso)

• Propósito: Omite las solicitudes de confirmación del usuario para operaciones destructivas

• ⚠️ Advertencia de seguridad: Esto es peligroso y solo debe usarse en entornos controlados

• Qué operaciones requieren confirmación normalmente:

  • create_secret - Crear nuevos secretos

  • update_secret - Modificar secretos existentes

  • delete_secret - Eliminar secretos

  • create_folder - Crear nuevas carpetas

  • delete_folder - Eliminar carpetas

  • upload_file - Subir archivos a secretos

  • Desenmascarar datos sensibles (contraseñas, claves API, etc.)

• Cuándo podrías usarlo:

  • Entornos de prueba automatizados

  • Agentes de IA de confianza en escenarios controlados

  • Operaciones masivas donde la confirmación manual no es práctica

• Alternativa recomendada: Usa la herramienta ksm_execute_confirmed_action para una aprobación selectiva

Variables de entorno

Prioridad de configuración

El servidor utiliza el siguiente orden de prioridad para la configuración:

1. Bandera CLI --config-base64 (prioridad más alta)

2. Variable de entorno KSM_CONFIG_BASE64

3. Bandera CLI --profile con almacenamiento de perfil local

4. Variable de entorno KSM_MCP_PROFILE con almacenamiento de perfil local

Comandos de gestión de perfiles

¿Por qué usar perfiles?

Los perfiles proporcionan una forma segura de almacenar y gestionar las configuraciones de KSM localmente sin exponer credenciales sensibles:

• Seguridad: Tu configuración en base64 contiene credenciales sensibles de la aplicación KSM. Los perfiles cifran y almacenan esto localmente con protección por contraseña

• Conveniencia: Una vez inicializado, solo necesitas hacer referencia al nombre del perfil en lugar de pasar la configuración completa en base64 cada vez

• Múltiples entornos: Gestiona diferentes aplicaciones KSM (dev, staging, prod) con perfiles separados

• Protección de credenciales: Mantiene los datos sensibles fuera de las líneas de comandos, variables de entorno y archivos de configuración

• Almacenamiento persistente: Sobrevive a los reinicios del sistema y no requiere volver a introducir las credenciales

Cuándo usar perfiles frente a la configuración directa:

• Usa perfiles para: Desarrollo local, configuraciones persistentes, múltiples entornos

• Usa configuración directa para: CI/CD, contenedores Docker, uso temporal, entornos donde no se desea almacenamiento local

Inicializar un nuevo perfil

ksm-mcp init --profile PROFILE_NAME --config "BASE64_CONFIG_STRING"

Este comando:

1. Toma tu configuración KSM en base64

2. La cifra con una contraseña que tú proporcionas

3. La almacena localmente en ~/.keeper/ksm-mcp/profiles/

4. Permite el uso futuro solo con --profile PROFILE_NAME

Listar perfiles disponibles

ksm-mcp profiles list

Eliminar un perfil

ksm-mcp profiles delete --profile PROFILE_NAME

Consideraciones de seguridad

Solución de problemas

Problemas comunes