Lightweight PowerShell MCP framework

Framework ligero de MCP para PowerShell. Expone funciones personalizadas de PowerShell a través de un servidor MCP puro en PowerShell para integrarse con agentes de IA compatibles con MCP.

GitHub

Documentación

Módulo de PowerShell para implementar un servidor MCP

PWSH MCP — Crea y expone automatización de PowerShell como herramientas MCP bajo demanda.

Descripción

El módulo de PowerShell para MCP te permite crear servidores del Protocolo de Contexto de Modelos (MCP) directamente desde funciones de PowerShell.

En lugar de escribir un servidor desde cero, defines funcionalidad como funciones de PowerShell y la expones a clientes MCP mediante JSON-RPC 2.0 sobre transporte stdio.

Alcance de implementación actual: herramientas MCP sobre transporte stdio. Los recursos, prompts y transportes basados en HTTP no están implementados.

Este enfoque es útil para desarrollo, gestión de infraestructura y escenarios de automatización CI/CD donde ya existen scripts de PowerShell que necesitan exponerse como herramientas estructuradas para asistentes de IA.

Por qué PowerShell para Servidores MCP:

PowerShell combina un ecosistema de automatización maduro con soporte multiplataforma.

Reutiliza automatización existente – expone scripts establecidos y módulos como Azure, AWS, VMware, Active Directory y herramientas de Exchange sin reescribirlos.
Integración multiplataforma – ejecuta el mismo servidor MCP en Windows, Linux y macOS.
Herramientas comprobables y validadas – prueba funciones de forma independiente con Pester y usa atributos de parámetros nativos para validación declarativa de entradas.
Esquemas impulsados por metadatos – usa Ayuda Basada en Comentarios y atributos de parámetros para mantener la documentación alineada con el JSON Schema generado automáticamente.

Características

Implementación pura en PowerShell – sin dependencias de runtime externas, aprovecha las capacidades nativas de PowerShell.
Servidor MCP basado en stdio – implementación de transporte stdio para integración con clientes MCP como GitHub Copilot y Gemini CLI.
Soporte multiplataforma – comportamiento consistente en todas las plataformas (Windows, Linux, macOS) con el mismo código base.
Generación automática de esquemas – convierte tipos de parámetros de funciones de PowerShell compatibles y Ayuda Basada en Comentarios en definiciones JSON Schema para herramientas MCP.
Validación de parámetros – aprovecha los atributos declarativos de validación de PowerShell para entradas de herramientas MCP con seguridad de tipos.

Resumen de Arquitectura

El módulo implementa el ciclo de vida de MCP sobre stdio y JSON-RPC 2.0:

Transporte stdio – la comunicación ocurre exclusivamente a través de stdin/stdout; no se requieren endpoints HTTP.
JSON-RPC 2.0 – las solicitudes y respuestas siguen la especificación JSON-RPC 2.0 con validación estricta y códigos de error predecibles.
Descubrimiento de herramientas (tools/list) – descubre y exporta funciones de PowerShell seleccionadas como herramientas MCP, incluyendo su esquema y metadatos.
Ejecución de herramientas (tools/call) – las llamadas entrantes de herramientas MCP se asignan a invocaciones de funciones de PowerShell, con enlace y validación automática de parámetros.
Inicialización y cierre – admite los métodos MCP principales.

Consideraciones de seguridad:

Saneamiento de solicitudes entrantes para prevenir ejecución no intencionada de comandos provocada por entradas generadas por IA.
La validación de parámetros de funciones garantiza que las entradas coincidan con los tipos, rangos y patrones esperados.
Aprovecha las características de seguridad nativas de PowerShell como firma de scripts y políticas de ejecución.
El servidor MCP puede ejecutarse dentro de un contenedor Docker para aislamiento adicional al exponer capacidades de automatización.

Casos de Uso

Los escenarios típicos incluyen:

Desarrollo rápido de herramientas – convierte scripts de administración existentes en herramientas MCP reutilizables o prototipa utilidades específicas de equipo.
Automatización DevOps y CI/CD – expone pipelines de despliegue, flujos de trabajo de infraestructura como código, artefactos de compilación, puertas de liberación y pasos de validación.
Gestión de infraestructura – gestiona recursos en la nube y locales, o construye flujos de monitoreo y alertas con módulos de PowerShell existentes.
Automatización empresarial – integra sistemas basados en REST o SDK, verificaciones de cumplimiento, pipelines de auditoría, informes y análisis.

Requisitos

PowerShell 7.5 o posterior (multiplataforma)
Cliente MCP que admita transporte stdio (Visual Studio Code con GitHub Copilot, Gemini CLI, Copilot CLI).

Compatibilidad

Cualquier cliente compatible con MCP que implemente el transporte stdio de MCP y los métodos MCP principales debería poder conectarse a un servidor MCP de PowerShell con la configuración adecuada.

El repositorio actualmente incluye documentación y ejemplos para los siguientes clientes MCP:

GitHub Copilot – asistente de codificación con IA.
GitHub Copilot CLI – configuración del servidor MCP.
Gemini CLI – asistente de IA de línea de comandos con soporte MCP.
Claude Desktop – configuración local del servidor MCP.

Primeros Pasos

El proyecto incluye ejemplos listos para usar y plantillas de configuración para un inicio rápido. Para uso detallado y configuración avanzada, consulta la guía de usuario y la guía de desarrollador.

Asegúrate de que los requisitos previos estén instalados (consulta Requisitos).
Crea un servidor MCP basado en PowerShell.
Agrega una entrada de configuración del servidor MCP a tu cliente MCP.
Llama a las herramientas MCP desde el cliente MCP.

Ejemplo de Servidor MCP Simple ...

⏺ Instalación desde PowerShell Gallery

Install-Module -Name pwsh.mcp

Este ejemplo muestra cómo exponer una función simple de PowerShell como una herramienta MCP.

⏺ Crea un script de PowerShell que defina una o más funciones e importe el módulo MCP de PowerShell.

# Import the MCP server module
Import-Module pwsh.mcp -Force -ErrorAction Stop

# Define a simple echo function
function get_echo {
    [CmdletBinding()]
    param (
      [Parameter(Mandatory = $false, HelpMessage = "Text to echo")]
      [string] $text = "Lorem Ipsum"
    )
    return "Echo, $text!"
}

# Start the MCP server and pass the functions to expose.
New-MCPServer -FunctionInfo (Get-Item Function:get_echo)

⏺ Agrega una configuración de servidor MCP (Visual Studio Code):

Agrega una nueva entrada a tu archivo mcp.json como se describe en la documentación oficial de Visual Studio Code.

Ejemplo de configuración .vscode/mcp.json para el script anterior:

{
  "servers": {
    "mcp-pwsh-server": {
      "type": "stdio",
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-NoLogo",
        "-File",
        "${workspaceFolder}/path/to/your/script.ps1"
      ]
    }
  }
}

La ruta del archivo puede ser absoluta o relativa a la carpeta del espacio de trabajo.

Consulta la guía de usuario para ejemplos adicionales y configuración avanzada.

Para configurar un cliente MCP, consulta la documentación oficial del cliente correspondiente:

⏺ Llama a la herramienta MCP desde tu cliente MCP (por ejemplo, GitHub Copilot en Visual Studio Code):

#get_echo text="Hello, MCP!"

Documentación

Guía de Usuario – documentación detallada de uso, incluyendo configuración avanzada, generación de esquemas y mejores prácticas.
Guía de Desarrollador – orientación para contribuciones, incluyendo estándares de codificación, pruebas y procesos CI/CD.

Referencias

Licencia

Este proyecto está licenciado bajo la Licencia MIT.