AI导哈

PowerShell MCP服务器

一个将PowerShell cmdlet暴露为AI助手工具的MCP服务器，通过白名单机制确保安全性。

  • by cezarypiatek
  • PowerShell
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 cezarypiatek/PoshMCP

使用说明

PowerShell MCP服务器

一个模型上下文协议（MCP）服务器，它将PowerShell cmdlet作为Claude或Github Copilot等AI助手的工具公开。通过明确列出允许的cmdlet，在构建时考虑了安全性。

概述

此MCP服务器从模块和脚本动态加载PowerShell cmdlet，从cmdlet文档自动生成工具架构。与传统的PowerShell远程处理不同，此服务器使用 白名单方法 -只公开显式配置的cmdlet，使AI交互更安全。

主要特点

  • 声明性配置：在简单的JSON配置文件中定义可用工具
  • 自动模式生成：使用PowerShell反射从cmdlet帮助文档生成MCP工具架构
  • 白名单安全：只有明确列出的cmdlet才会作为工具公开
  • 动态加载：支持PowerShell模块（.psm1）和脚本文件（.ps1）
  • 类型转换：自动处理参数类型转换（DateTime、开关参数等）

运作原理

  1. 配置加载：阅读 mcp-config.json 确定要公开哪些cmdlet
  2. 模块/脚本导入：加载指定的PowerShell模块和点源脚本文件
  3. 模式生成：用途 Get-Command 和 Get-Help 要检查每个cmdlet，请执行以下操作：
    • 提取cmdlet概要作为工具描述
    • 将PowerShell参数类型映射到JSON模式类型
    • 从中识别强制参数 [Parameter(Mandatory)] 属性
    • 为JSON生成camelCase参数名称（例如。， StartDate → startDate)
  4. 工具调用：调用工具时，使用参数映射动态分派到相应的cmdlet

安装

来自PowerShell库（推荐）

Install-Module -Name PoshMCP -Scope CurrentUser

来源

  1. 将此存储库克隆或下载到本地计算机
  2. 确保已安装PowerShell 7+(pwsh)

配置

MCP服务器配置

将以下内容添加到VS Code MCP配置文件中（通常 %APPDATA%\Code\User\mcp.json 在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"
            ]
        }
    }
}

工具配置

编辑 mcp-config.json 定义要公开的cmdlet：

{
    "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"
            ]
        }
    ]
}

配置结构：

  • serverInfo：关于MCP服务器的元数据

    • name：显示给MCP客户端的服务器名称
    • version：服务器版本

  • modules：要导入的PowerShell模块

    • name：模块名称（信息性）
    • path：到的相对或绝对路径 .psm1 文件
    • cmdlets：要作为工具公开的cmdlet名称数组

  • scripts：指向点源的PowerShell脚本文件

    • path：到的相对或绝对路径 .ps1 文件
    • cmdlets：要作为工具公开的函数名数组

创建自定义工具

示例：创建自定义脚本

创建脚本文件（例如。， 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
    }
}

添加到 mcp-config.json:

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

该工具将自动显示为 getSystemUptime （camelCase），其中包含基于注释的帮助生成的模式。

文档最佳实践

为了获得最佳效果，请在cmdlet中包含完整的基于注释的帮助：

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
}

安全考虑

为什么这更安全

  1. 仅限白名单：中仅明确列出了cmdlet mcp-config.json 可访问
  2. 无动态执行：服务器不执行任意PowerShell命令
  3. 参数验证：所有参数都经过PowerShell的本机验证
  4. 隔离范围：每个cmdlet都在受控上下文中运行

相关 MCP