winrm-mcp

Un servidor MCP deliberadamente pequeño para ejecutar comandos de PowerShell y CMD en hosts de Windows a través de WinRM. Toma las ideas de ejecución de WinRM de ssh-winrm-mcp, añade un inventario específico para múltiples hosts y excluye SSH, las sesiones persistentes, los trabajos, los grupos de comandos y la transferencia de archivos.

Herramientas

• winrm_test — verifica la autenticación y la conectividad.

• winrm_execute_powershell — ejecuta PowerShell.

• winrm_execute_cmd — ejecuta CMD.

• winrm_inventory_status, winrm_inventory_init, winrm_inventory_validate — administran los archivos de inventario.

• winrm_host_list, winrm_host_get, winrm_host_save, winrm_host_update, winrm_host_delete — administran hosts reutilizables.

Cada herramienta acepta un objeto connection opcional. Los valores que contiene anulan el entorno del proceso:

{
  "host": "192.168.1.50",
  "username": "Administrator",
  "password_env": "MY_WINRM_PASSWORD",
  "auth": "ntlm",
  "ssl": true,
  "cert_validation": false
}

ssl selecciona HTTPS (normalmente el puerto 5986) frente a HTTP (normalmente el puerto 5985). cert_validation=false es necesario para servidores HTTPS con certificados autofirmados, pero solo debe utilizarse para hosts de confianza.

Los campos de conexión admitidos son host, username, password, password_env, port, ssl, auth, cert_validation, encryption, path, connect_timeout, read_timeout y operation_timeout.

Related MCP server: Win MCP Server

Inventario de múltiples hosts

Los hosts se pueden almacenar en cualquiera de los dos ámbitos de inventario:

• user (predeterminado): ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json en Linux/macOS, o la ubicación equivalente de %APPDATA% en Windows.

• project: .winrm-mcp/inventory.json bajo el directorio de trabajo actual.

Elija el valor predeterminado del proceso con WINRM_MCP_INVENTORY_SCOPE=user o WINRM_MCP_INVENTORY_SCOPE=project. Todas las herramientas de inventario y de hosts aceptan también un scope explícito, y las herramientas de ejecución aceptan inventory_scope. El ámbito de proyecto usa WINRM_MCP_PROJECT_DIR, luego el PWD lógico del lanzador y, después, el directorio de trabajo del proceso. Rechaza las rutas temporales deepagents_server_* en lugar de guardar silenciosamente datos de inventario desechables. Establezca WINRM_MCP_PROJECT_DIR cuando el directorio de trabajo del lanzador no sea la raíz del proyecto deseada. Se admite un archivo totalmente personalizado mediante WINRM_MCP_INVENTORY_FILE; se usa cuando una llamada no selecciona explícitamente un ámbito.

Cree un inventario de proyecto y guarde dos hosts:

winrm_inventory_init(scope="project")

winrm_host_save(
  name="epv1",
  scope="project",
  settings={
    "host": "10.0.110.50",
    "username": "Administrator",
    "password_env": "EPV1_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

winrm_host_save(
  name="epv2",
  scope="project",
  settings={
    "host": "10.0.110.51",
    "username": "Administrator",
    "password_env": "EPV2_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

Use un host guardado por su nombre:

winrm_test(saved_host="epv1", inventory_scope="project")
winrm_execute_powershell(saved_host="epv1", inventory_scope="project", command="hostname")
winrm_execute_cmd(saved_host="epv2", inventory_scope="project", command="whoami")

El objeto opcional connection sobrescribe los campos del host guardado para esa llamada. Las escrituras en el inventario son atómicas, y el archivo de inventario está restringido al usuario actual (0600) en sistemas tipo Unix. Se admiten contraseñas en línea, pero se almacenan como texto plano en ese archivo JSON protegido; se prefiere password_env.

Omita connection cuando no se necesiten anulaciones. Para la compatibilidad con agentes que serializan un valor opcional como texto, connection="None", connection="null" y una cadena de conexión vacía se tratan como JSON null.

DeepAgents

DeepAgents puede ejecutar el servidor directamente desde GitHub, por lo que no se requiere una copia local. Añada la siguiente entrada al archivo .deepagents/.mcp.json de DeepAgents:

{
  "winrm": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "tool",
      "run",
      "--with",
      "mcp>=1.28,<2",
      "--from",
      "git+https://github.com/bigbatmanorg/winrm-mcp.git",
      "winrm-mcp"
    ],
    "env": {
      "WINRM_MCP_HOST": "192.168.1.50",
      "WINRM_MCP_USERNAME": "Administrator",
      "WINRM_MCP_PASSWORD": "YOUR_SECRET",
      "WINRM_MCP_PORT": "5986",
      "WINRM_MCP_AUTH": "ntlm",
      "WINRM_MCP_SSL": "true",
      "WINRM_MCP_CERT_VALIDATION": "false",
      "WINRM_MCP_INVENTORY_SCOPE": "project",
      "WINRM_MCP_PROJECT_DIR": "${PWD}",
      "WINRM_MCP_CONNECT_TIMEOUT": "30",
      "WINRM_MCP_READ_TIMEOUT": "60",
      "WINRM_MCP_OPERATION_TIMEOUT": "30"
    }
  }
}

Para instalaciones reproducibles, fije el repositorio a una etiqueta de versión o a un commit:

"git+https://github.com/bigbatmanorg/winrm-mcp.git@YOUR_TAG_OR_COMMIT"

El ejemplo usa HTTPS con la verificación de certificados deshabilitada para un host de desarrollo de confianza con un certificado autofirmado. Mantenga WINRM_MCP_CERT_VALIDATION=true cuando el certificado del servidor sea de confianza. No haga commit de una contraseña real en el control de fuentes; use su flujo habitual de inyección de secretos de DeepAgents para WINRM_MCP_PASSWORD. DeepAgents expande ${PWD} antes de lanzar el servidor MCP. Sustitúyalo por una ruta absoluta si DeepAgents se lanza desde un lugar distinto de la raíz del proyecto.

Instalación y ejecución

uv sync --extra dev
uv run pytest
uv run winrm-mcp

El transporte predeterminado es stdio. Una configuración del cliente puede proporcionar valores predeterminados de conexión estables sin necesidad de poner credenciales en cada llamada a una herramienta:

{
  "servers": {
    "winrm": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/home/toor/projects/winrm-mcp", "run", "winrm-mcp"],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD_ENV": "MY_WINRM_PASSWORD",
        "MY_WINRM_PASSWORD": "replace-me",
        "WINRM_MCP_AUTH": "ntlm",
        "WINRM_MCP_SSL": "true",
        "WINRM_MCP_CERT_VALIDATION": "false"
      }
    }
  }
}

Los valores predeterminados de entorno disponibles se corresponden con los campos de conexión y usan el prefijo WINRM_MCP_. Los ajustes del servidor son WINRM_MCP_TRANSPORT, WINRM_MCP_SERVER_HOST y WINRM_MCP_SERVER_PORT. Los ajustes del inventario son WINRM_MCP_INVENTORY_SCOPE, WINRM_MCP_PROJECT_DIR y WINRM_MCP_INVENTORY_FILE.

Para compatibilidad con Kerberos o CredSSP, instale el extra opcional correspondiente:

uv sync --extra kerberos
uv sync --extra credssp