PowerShell MCP Server

Ein MCP (Model Context Protocol) Server zur Ausführung von PowerShell-Skripten, der sowohl den HTTP- als auch den STDIO-Betriebsmodus unterstützt.

Beschreibung

Der MCP PowerShell Server ermöglicht es KI-Assistenten, PowerShell-Befehle und -Skripte über das standardisierte MCP-Protokoll auszuführen. Der Server unterstützt zwei Betriebsmodi:

STDIO-Modus: Für die Integration mit gemini-cli und anderen lokalen MCP-Clients.
HTTP-Modus: Für Webanwendungen und die Netzwerkintegration über eine REST-API.

Welchen Modus wählen: HTTP oder STDIO?

Die Wahl zwischen mcp-powershell-http.ps1 und mcp-powershell-stdio.ps1 hängt davon ab, wie und von wo die Client-Anwendung mit dem Server interagieren wird.

mcp-powershell-http.ps1 (HTTP-Modus) arbeitet wie ein Kellner in einem Restaurant. Er nimmt Bestellungen (HTTP-Anfragen) von jedem Client im Netzwerk entgegen, leitet sie an die „Küche“ (PowerShell) weiter und gibt das fertige Ergebnis (HTTP-Antwort) zurück.
mcp-powershell-stdio.ps1 (STDIO-Modus) arbeitet wie ein persönlicher Assistent in der Küche. Er erhält Aufgaben direkt (über die Standardeingabe stdin) von einem steuernden Prozess (z. B. gemini-cli), der ihn selbst gestartet hat, und gibt das Ergebnis sofort zurück (über die Standardausgabe stdout).

Wann sollte der HTTP-Modus verwendet werden?

Sie sollten HTTP wählen, wenn eine Netzwerkkommunikation erforderlich ist.

Fernverwaltung: Die Client-Anwendung befindet sich auf einem anderen Computer.
Web-Integration: Sie müssen PowerShell-Skripte aus einer Webanwendung, einem Admin-Panel oder über AJAX-Anfragen aufrufen.
Microservice-Architektur: Andere Dienste in Ihrem Netzwerk müssen mit PowerShell interagieren.
Einfaches Testen: Sie möchten Werkzeuge wie curl, Postman oder Invoke-RestMethod zum Senden von Befehlen verwenden.

Einfach ausgedrückt: Wählen Sie HTTP, wenn sich zwischen dem Client und dem Server ein Netzwerk befindet.

Wann sollte der STDIO-Modus verwendet werden?

Dieser Modus ist ideal für eine lokale und sichere Integration.

Hauptszenario – Gemini CLI: Das gemini-cli-Werkzeug startet mcp-powershell-stdio.ps1 als untergeordneten Prozess und kommuniziert direkt über die Standard-Ein-/Ausgabeströme mit ihm.
Integration mit anderen lokalen Anwendungen: Ihr Programm in Python, Node.js oder einer anderen Sprache kann den Server starten und verwalten, ohne Netzwerkports zu öffnen.
Erhöhte Sicherheit: Da keine Netzwerkports geöffnet werden, ist diese Methode standardmäßig sicherer.

Einfach ausgedrückt: Wählen Sie STDIO, wenn sich Client und Server auf derselben Maschine befinden und der Client den Server selbst startet.

Vergleichstabelle

Merkmal	HTTP-Modus (`mcp-powershell-http.ps1`)	STDIO-Modus (`mcp-powershell-stdio.ps1`)
Hauptszenario	Netzwerkkommunikation, Web-API	Lokale Integration mit CLI-Werkzeugen
Kommunikationstyp	Client-Server über das Netzwerk (TCP/IP)	Interprozesskommunikation (IPC)
Standort	Client und Server können sich auf unterschiedlichen Maschinen befinden	Client und Server müssen sich auf derselben Maschine befinden
Sicherheit	Erfordert Aufmerksamkeit (Portzugriff, Firewall)	Standardmäßig sicherer (keine offenen Ports)
Typische Clients	`curl`, Postman, Webanwendungen, Remote-Skripte	`gemini-cli`, lokale Wrapper-Anwendungen

Funktionen

✅ Unterstützung für das MCP-Protokoll Version 2024-11-05
✅ Zwei Betriebsmodi: STDIO und HTTP
✅ Isolierung der Skriptausführung in separaten PowerShell-Prozessen
✅ Konfigurierbare Ausführungs-Timeouts
✅ Detaillierte Protokollierung aller Vorgänge
✅ Behandlung von PowerShell-Fehlern und -Warnungen
✅ Unterstützung für Skriptparameter
✅ Konfigurierbares Arbeitsverzeichnis
✅ Automatische Launcher zur Vereinfachung des Starts

Systemanforderungen

PowerShell 7.0 oder neuer
Windows 10/11 oder Windows Server 2019+
.NET 6.0 oder neuer

Projektstruktur

mcp-powershell-server/
├── src/
│   ├── clients/           # Client-Anwendungen
│   │   ├── node/         # Node.js-Client
│   │   ├── powershell/   # PowerShell-Client
│   │   └── python/       # Python-Client
│   └── servers/          # Server-Komponenten
│       ├── mcp-powershell-stdio.ps1   # STDIO-Version des Servers
│       ├── mcp-powershell-http.ps1    # HTTP-Version des Servers
│       ├── test-mcp.ps1               # Testserver
│       └── config.json                # Konfigurationsdatei
├── docs/                 # Dokumentation
├── README.md            # Diese Datei
└── how-to-use.md        # Detaillierte Anleitung

Schnellstart

STDIO-Modus (für gemini-cli)

Server starten:
powershell .\src\servers\mcp-powershell-stdio.ps1
Testen:
powershell .\src\servers\test-mcp.ps1

HTTP-Modus

Grundlegender Start:
powershell .\src\servers\mcp-powershell-http.ps1
Mit benutzerdefinierten Parametern:
powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
Mit Konfigurationsdatei:
powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Verfügbare MCP-Werkzeuge

`run-script`

Führt ein PowerShell-Skript mit den angegebenen Parametern aus.

Parameter:

script (erforderlich) – Auszuführender PowerShell-Code
parameters (optional) – Hashtabelle mit Parametern
workingDirectory (optional) – Arbeitsverzeichnis
timeoutSeconds (optional) – Ausführungs-Timeout (1-3600 Sek.)

Anwendungsbeispiel über MCP:

{
  "name": "run-script",
  "arguments": {
    "script": "Get-Process | Select-Object -First 5 | Format-Table",
    "workingDirectory": "C:\\",
    "timeoutSeconds": 30
  }
}

Konfiguration

Der Server unterstützt die Konfiguration über die Datei config.json:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Tools\\"
  ],
  "Security": {
    "EnableScriptValidation": true,
    "BlockDangerousCommands": true,
    "RestrictedCommands": [
      "Remove-Item",
      "Format-Volume",
      "Stop-Computer",
      "Restart-Computer"
    ]
  }
}

Sicherheit

Die Skriptausführung erfolgt in isolierten PowerShell-Prozessen
Unterstützung einer Liste verbotener Befehle
Begrenzung der Ausführungszeit
Protokollierung aller ausgeführten Befehle
Möglichkeit zur Einschränkung der verfügbaren Pfade

Protokollierung (Logging)

STDIO-Modus: Protokolle werden in %TEMP%\mcp-powershell-server.log geschrieben
HTTP-Modus: Protokolle werden in der Konsole mit farblicher Hervorhebung ausgegeben

Protokollstufen: DEBUG, INFO, WARNING, ERROR

Integration mit KI-Assistenten

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Zeige die ersten 5 Prozesse im System an"

Andere MCP-Clients

Der Server ist mit allen Clients kompatibel, die das MCP-Protokoll 2024-11-05 unterstützen.

Fehlerbehebung

Häufige Probleme

Port belegt: Ändern Sie den Port in der Konfiguration oder beenden Sie den Prozess, der den Port verwendet.
Zugriffsrechte: Das Ausführen auf privilegierten Ports (<1024) erfordert Administratorrechte.
Zeichenkodierung: Stellen Sie sicher, dass PowerShell auf UTF-8 konfiguriert ist.
PowerShell-Version: PowerShell 7+ ist erforderlich.

Diagnose

Überprüfen Sie die Serverprotokolle zur Problemdiagnose:

Get-Content "$env:TEMP\mcp-powershell-server.log" -Tail 20

Entwicklung und Erweiterung

Der Server kann leicht um neue MCP-Werkzeuge erweitert werden. Siehe how-to-use.md für detaillierte Entwicklungsanweisungen.

Lizenz

Dieses Projekt wird unter der MIT-Lizenz vertrieben. Siehe die LICENSE-Datei für Details.

Support

Erstellen Sie ein „Issue“ im GitHub-Repository.
Überprüfen Sie die Dokumentation in how-to-use.md.
Sehen Sie sich die Anwendungsbeispiele an.

Versionen

1.0.0 – Erstversion mit Unterstützung für STDIO- und HTTP-Modi.