Servidor MCP PowerShell. README>

Un servidor MCP (Model Context Protocol) para ejecutar scripts de PowerShell, compatible con los modos de operación HTTP y STDIO.

In Questo Articolo

Descripción

El Servidor MCP PowerShell permite a los asistentes de IA ejecutar comandos y scripts de PowerShell a través del protocolo estandarizado MCP. El servidor admite dos modos de operación:

Modo STDIO: Para la integración con gemini-cli y otros clientes MCP locales.
Modo HTTP: Para aplicaciones web e integración a través de la red mediante una API REST.

¿Qué modo elegir: HTTP o STDIO?

La elección entre mcp-powershell-http.ps1 y mcp-powershell-stdio.ps1 depende de cómo y desde dónde la aplicación cliente interactuará con el servidor.

mcp-powershell-http.ps1 (modo HTTP) funciona como un camarero en un restaurante. Acepta pedidos (solicitudes HTTP) de cualquier cliente en la red, los pasa a la «cocina» (PowerShell) y devuelve el resultado listo (respuesta HTTP).
mcp-powershell-stdio.ps1 (modo STDIO) funciona como un asistente personal en la cocina. Recibe tareas directamente (a través de la entrada estándar stdin) de un proceso gestor (por ejemplo, gemini-cli) que él mismo ha iniciado, y devuelve el resultado inmediatamente (a través de la salida estándar stdout).

Cuándo usar el modo HTTP

Deberías elegir HTTP si se requiere interacción en red.

Gestión remota: La aplicación cliente se encuentra en otro ordenador.
Integración web: Es necesario llamar a scripts de PowerShell desde una aplicación web, un panel de administración o mediante solicitudes AJAX.
Arquitectura de microservicios: Otros servicios en tu red necesitan interactuar con PowerShell.
Pruebas sencillas: Quieres usar herramientas como curl, Postman o Invoke-RestMethod para enviar comandos.

En palabras simples: elige HTTP si hay una red entre el cliente y el servidor.

Cuándo usar el modo STDIO

Este modo es ideal para una integración local y segura.

Escenario principal — Gemini CLI: La herramienta gemini-cli inicia mcp-powershell-stdio.ps1 como un proceso hijo y se comunica con él directamente a través de los flujos de entrada/salida estándar.
Integración con otras aplicaciones locales: Tu programa en Python, Node.js u otro lenguaje puede iniciar y gestionar el servidor sin abrir puertos de red.
Seguridad mejorada: Dado que no se abren puertos de red, este método es más seguro por defecto.

En palabras simples: elige STDIO si el cliente y el servidor están en la misma máquina, y el cliente inicia el servidor por sí mismo.

Tabla comparativa

Característica	Modo HTTP (`mcp-powershell-http.ps1`)	Modo STDIO (`mcp-powershell-stdio.ps1`)
Escenario principal	Interacción en red, API web	Integración local con herramientas CLI
Tipo de comunicación	Cliente-servidor por red (TCP/IP)	Comunicación entre procesos (IPC)
Ubicación	El cliente y el servidor pueden estar en máquinas diferentes	El cliente y el servidor deben estar en la misma máquina
Seguridad	Requiere atención (acceso al puerto, firewall)	Más seguro por defecto (sin puertos abiertos)
Clientes típicos	`curl`, Postman, aplicaciones web, scripts remotos	`gemini-cli`, aplicaciones locales de envoltura

Características

✅ Soporte para el protocolo MCP versión 2024-11-05
✅ Dos modos de operación: STDIO y HTTP
✅ Aislamiento de la ejecución de scripts en procesos de PowerShell separados
✅ Tiempos de espera de ejecución configurables
✅ Registro detallado de todas las operaciones
✅ Manejo de errores y advertencias de PowerShell
✅ Soporte para parámetros de script
✅ Directorio de trabajo configurable
✅ Lanzadores automáticos para simplificar el inicio

Requisitos del sistema

PowerShell 7.0 o superior
Windows 10/11 o Windows Server 2019+
.NET 6.0 o superior

Estructura del proyecto

mcp-powershell-server/
├── src/
│   ├── clients/           # Aplicaciones cliente
│   │   ├── node/         # Cliente Node.js
│   │   ├── powershell/   # Cliente PowerShell
│   │   └── python/       # Cliente Python
│   └── servers/          # Componentes del servidor
│       ├── mcp-powershell-stdio.ps1   # Versión STDIO del servidor
│       ├── mcp-powershell-http.ps1    # Versión HTTP del servidor
│       ├── test-mcp.ps1               # Servidor de prueba
│       └── config.json                # Archivo de configuración
├── docs/                 # Documentación
├── README.md            # Este archivo
└── how-to-use.md        # Guía de uso detallada

Inicio rápido

Modo STDIO (para gemini-cli)

Iniciar el servidor:
powershell .\src\servers\mcp-powershell-stdio.ps1
Prueba:
powershell .\src\servers\test-mcp.ps1

Modo HTTP

Inicio básico:
powershell .\src\servers\mcp-powershell-http.ps1
Con parámetros personalizados:
powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
Con archivo de configuración:
powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Herramientas MCP disponibles

`run-script`

Ejecuta un script de PowerShell con los parámetros especificados.

Parámetros:

script (obligatorio) – Código PowerShell a ejecutar
parameters (opcional) – Tabla hash de parámetros
workingDirectory (opcional) – Directorio de trabajo
timeoutSeconds (opcional) – Tiempo de espera de ejecución (1-3600 seg)

Ejemplo de uso a través de MCP:

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

Configuración

El servidor admite la configuración a través del archivo 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"
    ]
  }
}

Seguridad

La ejecución de scripts se realiza en procesos de PowerShell aislados
Soporte para una lista de comandos prohibidos
Límite de tiempo de ejecución
Registro de todos los comandos ejecutados
Posibilidad de restringir las rutas accesibles

Registro (Logging)

Modo STDIO: Los registros se escriben en %TEMP%\mcp-powershell-server.log
Modo HTTP: Los registros se muestran en la consola con indicadores de color

Niveles de registro: DEBUG, INFO, WARNING, ERROR

Integración con asistentes de IA

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Muestra los primeros 5 procesos en el sistema"

Otros clientes MCP

El servidor es compatible con todos los clientes que admiten el protocolo MCP 2024-11-05.

Solución de problemas

Problemas comunes

Puerto ocupado: Cambia el puerto en la configuración o detén el proceso que usa el puerto.
Derechos de acceso: La ejecución en puertos privilegiados (<1024) requiere derechos de administrador.
Codificación: Asegúrate de que PowerShell esté configurado en UTF-8.
Versión de PowerShell: Se requiere PowerShell 7+.

Diagnóstico

Verifica los registros del servidor para diagnosticar problemas:

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

Desarrollo y extensión

El servidor se puede ampliar fácilmente con nuevas herramientas MCP. Consulta how-to-use.md para obtener instrucciones detalladas de desarrollo.

Licencia

Este proyecto se distribuye bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Soporte

Crea un «Issue» en el repositorio de GitHub.
Consulta la documentación en how-to-use.md.
Revisa los ejemplos de uso.

Versiones

1.0.0 – Versión inicial con soporte para los modos STDIO y HTTP.