winrm-mcp

Ein bewusst kleiner MCP-Server zum Ausführen von PowerShell- und CMD-Befehlen auf Windows-Hosts über WinRM. Er übernimmt die WinRM-Ausführungsideen von ssh-winrm-mcp, fügt ein fokussiertes Multi-Host-Inventar hinzu und lässt SSH, persistente Sitzungen, Jobs, Befehlsgruppen und Dateiübertragung weg.

Tools

• winrm_test — Authentifizierung und Konnektivität prüfen.

• winrm_execute_powershell — PowerShell ausführen.

• winrm_execute_cmd — CMD ausführen.

• winrm_inventory_status, winrm_inventory_init, winrm_inventory_validate — Inventardateien verwalten.

• winrm_host_list, winrm_host_get, winrm_host_save, winrm_host_update, winrm_host_delete — wiederverwendbare Hosts verwalten.

Jedes Tool akzeptiert ein optionales connection-Objekt. Werte darin überschreiben die Prozessumgebung:

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

ssl wählt HTTPS (normalerweise Port 5986) gegenüber HTTP (normalerweise Port 5985). cert_validation=false wird für selbstsignierte HTTPS-Listener benötigt, sollte aber nur für vertrauenswürdige Hosts verwendet werden.

Unterstützte Verbindungsfelder sind host, username, password, password_env, port, ssl, auth, cert_validation, encryption, path, connect_timeout, read_timeout und operation_timeout.

Related MCP server: Win MCP Server

Multi-Host-Inventar

Hosts können in jedem der beiden Inventarbereiche gespeichert werden:

• user (Standard): ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json unter Linux/macOS oder der entsprechende %APPDATA%-Speicherort unter Windows.

• project: .winrm-mcp/inventory.json im aktuellen Arbeitsverzeichnis.

Wählen Sie den Prozessstandard mit WINRM_MCP_INVENTORY_SCOPE=user oder WINRM_MCP_INVENTORY_SCOPE=project. Jedes Inventar- und Host-Tool akzeptiert auch einen expliziten scope, und Ausführungstools akzeptieren inventory_scope. Der Projektbereich verwendet WINRM_MCP_PROJECT_DIR, dann das logische PWD des Starters, dann das aktuelle Arbeitsverzeichnis. Er lehnt temporäre deepagents_server_*-Pfade ab, anstatt vorübergehende Inventardaten stillschweigend zu speichern. Setzen Sie WINRM_MCP_PROJECT_DIR, wenn das Arbeitsverzeichnis des Starters nicht das gewünschte Projektstammverzeichnis ist. Eine vollständig benutzerdefinierte Datei wird über WINRM_MCP_INVENTORY_FILE unterstützt; sie wird verwendet, wenn ein Aufruf keinen expliziten Bereich auswählt.

Erstellen Sie ein Projektinventar und speichern Sie zwei 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
  }
)

Verwenden Sie einen gespeicherten Host per Name:

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")

Das optionale connection-Objekt überschreibt Felder des gespeicherten Hosts für diesen Aufruf. Inventar-Schreibvorgänge sind atomar, und die Inventardatei ist auf Unix-ähnlichen Systemen auf den aktuellen Benutzer beschränkt (0600). Inline-Passwörter werden unterstützt, aber als Klartext in dieser geschützten JSON-Datei gespeichert; bevorzugen Sie password_env.

Lassen Sie connection weg, wenn keine Übersteuerungen benötigt werden. Für Kompatibilität mit Agenten, die einen optionalen Wert als Text serialisieren, werden connection="None", connection="null" und eine leere Verbindungszeichenfolge als JSON null behandelt.

DeepAgents

DeepAgents kann den Server direkt von GitHub ausführen, sodass ein lokaler Checkout nicht erforderlich ist. Fügen Sie den folgenden Eintrag zu Ihrer DeepAgents-Datei .deepagents/.mcp.json hinzu:

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

Für reproduzierbare Installationen binden Sie das Repository an einen Release-Tag oder Commit:

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

Das Beispiel verwendet HTTPS mit deaktivierter Zertifikatsprüfung für einen vertrauenswürdigen Entwicklungshost mit einem selbstsignierten Zertifikat. Behalten Sie WINRM_MCP_CERT_VALIDATION=true bei, wenn das Listener-Zertifikat vertrauenswürdig ist. Committen Sie kein echtes Passwort in die Versionskontrolle; verwenden Sie für WINRM_MCP_PASSWORD Ihren üblichen DeepAgents-Geheim-Injektions-Workflow. DeepAgents erweitert ${PWD} vor dem Start des MCP-Servers. Ersetzen Sie es durch einen absoluten Pfad, wenn DeepAgents selbst von einem anderen Ort als dem Projektstammverzeichnis gestartet wird.

Installation und Ausführung

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

Der Standardtransport ist stdio. Eine Client-Konfiguration kann stabile Verbindungsstandards bereitstellen, ohne Anmeldeinformationen in jeden Tool-Aufruf zu setzen:

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

Verfügbare Umgebungsstandards entsprechen den Verbindungsfeldern und verwenden das Präfix WINRM_MCP_. Servereinstellungen sind WINRM_MCP_TRANSPORT, WINRM_MCP_SERVER_HOST und WINRM_MCP_SERVER_PORT. Inventareinstellungen sind WINRM_MCP_INVENTORY_SCOPE, WINRM_MCP_PROJECT_DIR und WINRM_MCP_INVENTORY_FILE.

Für Kerberos- oder CredSSP-Unterstützung installieren Sie die passende optionale Erweiterung:

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