Serveur MCP PowerShell. README>

Un serveur MCP (Model Context Protocol) pour l’exécution de scripts PowerShell, prenant en charge les modes de fonctionnement HTTP et STDIO.

In Questo Articolo

Description

Le serveur MCP PowerShell permet aux assistants IA d’exécuter des commandes et des scripts PowerShell via le protocole standardisé MCP. Le serveur prend en charge deux modes de fonctionnement :

Mode STDIO : Pour l’intégration avec gemini-cli et d’autres clients MCP locaux.
Mode HTTP : Pour les applications web et l’intégration réseau via une API REST.

Quel mode choisir : HTTP ou STDIO ?

Le choix entre mcp-powershell-http.ps1 et mcp-powershell-stdio.ps1 dépend de comment et d’où l’application cliente interagira avec le serveur.

mcp-powershell-http.ps1 (mode HTTP) fonctionne comme un serveur dans un restaurant. Il prend les commandes (requêtes HTTP) de n’importe quel client sur le réseau, les transmet à la « cuisine » (PowerShell) et renvoie le résultat prêt (réponse HTTP).
mcp-powershell-stdio.ps1 (mode STDIO) fonctionne comme un assistant personnel en cuisine. Il reçoit les tâches directement (via l’entrée standard stdin) d’un processus de gestion (par exemple, gemini-cli) qui l’a lui-même lancé, et renvoie immédiatement le résultat (via la sortie standard stdout).

Quand utiliser le mode HTTP

Vous devriez choisir HTTP si une interaction réseau est requise.

Gestion à distance : L’application cliente se trouve sur un autre ordinateur.
Intégration web : Nécessité d’appeler des scripts PowerShell depuis une application web, un panneau d’administration ou via des requêtes AJAX.
Architecture microservices : D’autres services de votre réseau doivent interagir avec PowerShell.
Tests simples : Vous souhaitez utiliser des outils comme curl, Postman ou Invoke-RestMethod pour envoyer des commandes.

En termes simples : choisissez HTTP s’il y a un réseau entre le client et le serveur.

Quand utiliser le mode STDIO

Ce mode est idéal pour une intégration locale et sécurisée.

Scénario principal — Gemini CLI : L’outil gemini-cli lance lui-même mcp-powershell-stdio.ps1 en tant que processus enfant et communique directement avec lui via les flux d’entrée/sortie standard.
Intégration avec d’autres applications locales : Votre programme en Python, Node.js ou un autre langage peut démarrer et gérer le serveur sans ouvrir de ports réseau.
Sécurité renforcée : Comme aucun port réseau n’est ouvert, cette méthode est plus sûre par défaut.

En termes simples : choisissez STDIO si le client et le serveur sont sur la même machine, et que le client lance lui-même le serveur.

Tableau comparatif

Caractéristique	Mode HTTP (`mcp-powershell-http.ps1`)	Mode STDIO (`mcp-powershell-stdio.ps1`)
Scénario principal	Interaction réseau, API web	Intégration locale avec des outils CLI
Type de communication	Client-serveur sur le réseau (TCP/IP)	Communication inter-processus (IPC)
Emplacement	Le client et le serveur peuvent être sur des machines différentes	Le client et le serveur doivent être sur la même machine
Sécurité	Nécessite de l’attention (accès au port, pare-feu)	Plus sûr par défaut (pas de ports ouverts)
Clients typiques	`curl`, Postman, applications web, scripts distants	`gemini-cli`, applications locales (wrappers)

Fonctionnalités

✅ Prise en charge du protocole MCP version 2024-11-05
✅ Deux modes de fonctionnement : STDIO et HTTP
✅ Isolation de l’exécution des scripts dans des processus PowerShell distincts
✅ Délais d’attente (timeouts) d’exécution configurables
✅ Journalisation détaillée de toutes les opérations
✅ Gestion des erreurs et des avertissements PowerShell
✅ Prise en charge des paramètres de script
✅ Répertoire de travail configurable
✅ Lanceurs automatiques pour un démarrage simplifié

Prérequis système

PowerShell 7.0 ou plus récent
Windows 10/11 ou Windows Server 2019+
.NET 6.0 ou plus récent

Structure du projet

mcp-powershell-server/
├── src/
│   ├── clients/           # Applications clientes
│   │   ├── node/         # Client Node.js
│   │   ├── powershell/   # Client PowerShell
│   │   └── python/       # Client Python
│   └── servers/          # Composants serveur
│       ├── mcp-powershell-stdio.ps1   # Version STDIO du serveur
│       ├── mcp-powershell-http.ps1    # Version HTTP du serveur
│       ├── test-mcp.ps1               # Serveur de test
│       └── config.json                # Fichier de configuration
├── docs/                 # Documentation
├── README.md            # Ce fichier
└── how-to-use.md        # Guide d'utilisation détaillé

Démarrage rapide

Mode STDIO (pour gemini-cli)

Démarrer le serveur :
powershell .\src\servers\mcp-powershell-stdio.ps1
Tester :
powershell .\src\servers\test-mcp.ps1

Mode HTTP

Démarrage de base :
powershell .\src\servers\mcp-powershell-http.ps1
Avec des paramètres personnalisés :
powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
Avec un fichier de configuration :
powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Outils MCP disponibles

`run-script`

Exécute un script PowerShell avec les paramètres spécifiés.

Paramètres :

script (obligatoire) – Code PowerShell à exécuter
parameters (optionnel) – Table de hachage des paramètres
workingDirectory (optionnel) – Répertoire de travail
timeoutSeconds (optionnel) – Délai d’attente d’exécution (1-3600 sec)

Exemple d’utilisation via MCP :

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

Configuration

Le serveur prend en charge la configuration via le fichier 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"
    ]
  }
}

Sécurité

L’exécution des scripts se fait dans des processus PowerShell isolés
Prise en charge d’une liste de commandes interdites
Limitation du temps d’exécution
Journalisation de toutes les commandes exécutées
Possibilité de restreindre les chemins d’accès autorisés

Journalisation (Logging)

Mode STDIO : Les journaux sont écrits dans %TEMP%\mcp-powershell-server.log
Mode HTTP : Les journaux sont affichés dans la console avec une coloration syntaxique

Niveaux de journalisation : DEBUG, INFO, WARNING, ERROR

Intégration avec les assistants IA

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Affiche les 5 premiers processus du système"

Autres clients MCP

Le serveur est compatible avec tous les clients prenant en charge le protocole MCP 2024-11-05.

Dépannage

Problèmes courants

Port occupé : Changez le port dans la configuration ou arrêtez le processus qui utilise le port.
Droits d’accès : Le lancement sur des ports privilégiés (<1024) nécessite des droits d'administrateur.
Encodage : Assurez-vous que PowerShell est configuré en UTF-8.
Version de PowerShell : PowerShell 7+ est requis.

Diagnostic

Vérifiez les journaux du serveur pour diagnostiquer les problèmes :

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

Développement et extension

Le serveur est facilement extensible avec de nouveaux outils MCP. Consultez how-to-use.md pour des instructions de développement détaillées.

Licence

Ce projet est distribué sous la licence MIT. Voir le fichier LICENSE pour plus de détails.

Support

Créez une « Issue » dans le dépôt GitHub.
Consultez la documentation dans how-to-use.md.
Familiarisez-vous avec les exemples d’utilisation.

Versions

1.0.0 – Version initiale avec prise en charge des modes STDIO et HTTP.