PoshMCP

Servidor MCP de PowerShell

Un servidor de Model Context Protocol (MCP) que expone cmdlets de PowerShell como herramientas para asistentes de IA como Claude o Github Copilot. Construido con seguridad en mente mediante la inclusión explícita en listas blancas de cmdlets permitidos.

Descripción general

Este servidor MCP carga dinámicamente cmdlets de PowerShell desde módulos y scripts, generando automáticamente esquemas de herramientas a partir de la documentación de los cmdlets. A diferencia del remoting tradicional de PowerShell, este servidor utiliza un enfoque de lista blanca: solo se exponen los cmdlets configurados explícitamente, lo que lo hace más seguro para interacciones con IA.

Características clave

• Configuración declarativa: Define las herramientas disponibles en un archivo JSON simple
• Generación automática de esquemas: Utiliza reflexión de PowerShell para generar esquemas de herramientas MCP a partir de la documentación de ayuda de los cmdlets
• Seguridad mediante lista blanca: Solo los cmdlets listados explícitamente se exponen como herramientas
• Carga dinámica: Admite tanto módulos de PowerShell (.psm1) como archivos de script (.ps1)
• Conversión de tipos: Maneja automáticamente las conversiones de tipos de parámetros (DateTime, parámetros de conmutación, etc.)

Cómo funciona

1. Carga de configuración: Lee mcp-config.json para determinar qué cmdlets exponer
2. Importación de módulos/scripts: Carga los módulos de PowerShell especificados y aplica dot-source a los archivos de script
3. Generación de esquemas: Utiliza Get-Command y Get-Help para inspeccionar cada cmdlet:
   • Extrae el resumen del cmdlet como descripción de la herramienta
   • Mapea los tipos de parámetros de PowerShell a tipos de esquema JSON
   • Identifica los parámetros obligatorios a partir de los atributos [Parameter(Mandatory)]
   • Genera nombres de parámetros en camelCase para JSON (por ejemplo, StartDate → startDate)
4. Invocación de herramientas: Cuando se llama a una herramienta, se despacha dinámicamente al cmdlet correspondiente con el mapeo de parámetros

Instalación

Desde PowerShell Gallery (Recomendado)

Install-Module -Name PoshMCP -Scope CurrentUser

Desde el código fuente

1. Clona o descarga este repositorio en tu máquina local
2. Asegúrate de tener PowerShell 7+ instalado (pwsh)

Configuración

Configuración del servidor MCP

Agrega lo siguiente a tu archivo de configuración MCP de VS Code (típicamente %APPDATA%\Code\User\mcp.json en Windows):

{
    "servers": {
        "posh-mcp": {
            "type": "stdio",
            "command": "pwsh",
            "args": [
                "-NoProfile",
                "-NoLogo",
                "-Command",
                "Import-Module PoshMCP;",
                "Start-PoshMcp -ConfigPath C:\\path\\to\\your\\mcp-config.json"
            ]
        }
    }
}

Configuración de herramientas

Edita mcp-config.json para definir qué cmdlets exponer:

{
    "serverInfo": {
        "name": "posh-mcp",
        "version": "1.0.0"
    },
    "modules": [
        {
            "name": "ModuleName",
            "path": "./MyModule.psm1",
            "cmdlets": [
                "Get-MyData",
                "Set-MyConfig"
            ]
        }
    ],
    "scripts": [
        {
            "path": "./my-tools.ps1",
            "cmdlets": [
                "Get-CustomInfo",
                "Invoke-CustomTask"
            ]
        }
    ]
}

Estructura de configuración:

• serverInfo: Metadatos sobre el servidor MCP

  • name: Nombre del servidor mostrado a los clientes MCP
  • version: Versión del servidor

• modules: Módulos de PowerShell a importar

  • name: Nombre del módulo (informativo)
  • path: Ruta relativa o absoluta al archivo .psm1
  • cmdlets: Matriz de nombres de cmdlets a exponer como herramientas

• scripts: Archivos de script de PowerShell a los que aplicar dot-source

  • path: Ruta relativa o absoluta al archivo .ps1
  • cmdlets: Matriz de nombres de funciones a exponer como herramientas

Creación de herramientas personalizadas

Ejemplo: Creación de un script personalizado

Crea un archivo de script (por ejemplo, my-tools.ps1):

function Get-SystemUptime {
    <#
    .SYNOPSIS
        Returns the system uptime information.
    
    .DESCRIPTION
        Gets how long the system has been running since last boot.
    
    .EXAMPLE
        Get-SystemUptime
        Returns uptime information.
    
    .OUTPUTS
        Hashtable with uptime details.
    #>
    [CmdletBinding()]
    param()
    
    $os = Get-CimInstance Win32_OperatingSystem
    $uptime = (Get-Date) - $os.LastBootUpTime
    
    return @{
        LastBootTime = $os.LastBootUpTime.ToString("o")
        UptimeDays = $uptime.Days
        UptimeHours = $uptime.Hours
        UptimeMinutes = $uptime.Minutes
    }
}

Agrega a mcp-config.json:

{
    "scripts": [
        {
            "path": "./my-tools.ps1",
            "cmdlets": [
                "Get-SystemUptime"
            ]
        }
    ]
}

La herramienta se expondrá automáticamente como getSystemUptime (camelCase) con el esquema generado a partir de la ayuda basada en comentarios.

Mejores prácticas de documentación

Para obtener los mejores resultados, incluye ayuda completa basada en comentarios en tus cmdlets:

function Get-MyData {
    <#
    .SYNOPSIS
        Brief one-line description (becomes tool description)
    
    .PARAMETER Name
        Detailed parameter description (appears in tool schema)
    
    .PARAMETER StartDate
        Start date for filtering results
    
    .EXAMPLE
        Get-MyData -Name "Test" -StartDate "2025-01-01"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Name,
        
        [Parameter(Mandatory = $false)]
        [DateTime]$StartDate = (Get-Date).AddDays(-7)
    )
    
    # Your implementation
}

Consideraciones de seguridad

Por qué esto es más seguro

1. Solo lista blanca: Solo los cmdlets listados explícitamente en mcp-config.json son accesibles
2. Sin ejecución dinámica: El servidor no ejecuta comandos arbitrarios de PowerShell
3. Validación de parámetros: Todos los parámetros pasan por la validación nativa de PowerShell
4. Ámbito aislado: Cada cmdlet se ejecuta en un contexto controlado