AI导哈

PowerShell命令执行服务

一个支持在Windows系统上执行PowerShell命令的MCP服务器，兼容PowerShell 7+和Windows PowerShell 5.1，适用于自动化脚本执行和系统管理任务。

  • by suparious
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 suparious/mcp-powershell

使用说明

powershell mcp

一个强大的MCP（模型上下文协议）服务器，使Claude能够在Windows系统上执行PowerShell命令。同时支持PowerShell 7+（pwsh.exe）和Windows PowerShell 5.1（PowerShell.exe）。

⚠️ 安全警告：此服务器执行任意PowerShell命令。请谨慎使用，仅在受信任的环境中使用。

特性

  • 双PowerShell支持：使用现代PowerShell 7+或旧版Windows PowerShell 5.1
  • 智能默认值：默认情况下自动检测并使用PowerShell 7
  • 后台进程：运行和管理长时间运行的PowerShell脚本
  • 输出管理：自动截断和保存大输出文件
  • 脚本执行：运行带有参数的.ps1脚本文件
  • 版本检测：检查哪些PowerShell版本可用
  • 可配置的：用于自定义的环境变量

安装

方案1：地方发展（当前）

cd C:\Users\shaun\repos\mcp-powershell
npm install

选项2:NPM Global（未来）

npm install -g powershell-mcp

快速开始

Claude Desktop（本地开发）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["C:\\Users\\shaun\\repos\\mcp-powershell\\index.js"]
    }
  }
}

适用于Claude Desktop（NPM包-未来）

{
  "mcpServers": {
    "powershell": {
      "command": "npx",
      "args": ["powershell-mcp"]
    }
  }
}

配置选项

您可以使用环境变量自定义行为：

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["C:\\Users\\shaun\\repos\\mcp-powershell\\index.js"],
      "env": {
        "POWERSHELL_MCP_DEFAULT_SHELL": "pwsh",
        "POWERSHELL_MCP_MAX_OUTPUT_SIZE": "102400",
        "POWERSHELL_MCP_TEMP_DIR": "C:\\temp\\powershell-mcp",
        "POWERSHELL_MCP_PWSH_PATH": "pwsh.exe",
        "POWERSHELL_MCP_POWERSHELL_PATH": "powershell.exe"
      }
    }
  }
}

环境变量

变量 默认值 描述
POWERSHELL_MCP_DEFAULT_SHELL pwsh 要使用的默认shell： pwsh 或 powershell
POWERSHELL_MCP_MAX_OUTPUT_SIZE 51200 （50KB） 截断前的最大输出大小
POWERSHELL_MCP_TEMP_DIR 系统临时 用于存储完整输出的目录
POWERSHELL_MCP_PWSH_PATH pwsh.exe PowerShell 7可执行文件的路径
POWERSHELL_MCP_POWERSHELL_PATH powershell.exe Windows PowerShell 5.1可执行文件的路径

可用工具

run -执行PowerShell命令

执行任何PowerShell命令，并完全控制要使用的版本。

参数：

  • command （字符串，必填）：要执行的PowerShell命令
  • cwd （字符串，可选）：工作目录
  • timeout （数字，可选）：超时时间（毫秒）（默认值：30000）
  • useLegacy （布尔值，可选）：使用PowerShell 5.1而不是7（默认值：false）
  • asJson （boolean，可选）：如果可能，将输出解析为JSON（默认值：false）

示例：

// Simple command (uses PowerShell 7)
run("Get-Process | Select-Object -First 5")

// With working directory
run("Get-ChildItem", { cwd: "C:\\Projects" })

// Use legacy PowerShell 5.1 for compatibility
run("Get-WindowsFeature", { useLegacy: true })

// Parse JSON output
run("Get-Process | Select-Object Name, Id | ConvertTo-Json", { asJson: true })

run_script -执行PowerShell脚本文件

运行带有参数的.ps1脚本文件。

参数：

  • scriptPath （字符串，必填）：.ps1文件的路径
  • args （数组，可选）：传递给脚本的参数
  • cwd （字符串，可选）：工作目录
  • timeout （数字，可选）：超时时间（毫秒）（默认值：30000）
  • useLegacy （布尔值，可选）：使用PowerShell 5.1（默认值：false）

例子：

run_script("C:\\Scripts\\Deploy.ps1", {
  args: ["Production", "v1.2.3"],
  cwd: "C:\\Projects\\MyApp"
})

get_version -检查PowerShell版本

获取两个PowerShell安装的详细版本信息。

例子：

get_version()

退货：

{
  "success": true,
  "available": {
    "pwsh": true,
    "powershell": true
  },
  "defaultShell": "pwsh",
  "versions": {
    "PowerShell 7": {
      "PSVersion": "7.5.4",
      "PSEdition": "Core"
    },
    "PowerShell 5.1": {
      "PSVersion": "5.1.26100.6899",
      "PSEdition": "Desktop"
    }
  }
}

run_background -启动后台进程

在后台运行长时间运行的PowerShell命令。

参数：

  • command （字符串，必填）：PowerShell命令
  • name （字符串，必填）：进程的唯一名称
  • cwd （字符串，可选）：工作目录
  • useLegacy （布尔值，可选）：使用PowerShell 5.1（默认值：false）

例子：

run_background("npm run dev", "frontend-server")

kill_background -停止后台进程

按名称终止后台进程。

参数：

  • name （string，必填）：要终止的进程的名称

例子：

kill_background("frontend-server")

list_background -列出后台进程

列出所有正在运行的后台进程及其状态。

例子：

list_background()

PowerShell 7与Windows PowerShell 5.1

PowerShell 7（pwsh.exe）-默认值

优势：

  • 现代功能和更好的性能
  • 跨平台cmdlet
  • 定期更新
  • 更好的JSON处理
  • 改进了错误消息

在以下情况下使用：

  • 执行一般脚本任务
  • 使用现代API
  • 需要最新的PowerShell功能

Windows PowerShell 5.1（PowerShell.exe）

优势：

  • 配有Windows
  • 一些遗留模块仅在此处工作
  • 某些Windows管理工具

在以下情况下使用：

  • 需要特定的Windows专用模块
  • 使用遗留脚本
  • 兼容性要求

示例-使用传统模式：

// Some Windows features require PowerShell 5.1
run("Get-WindowsFeature", { useLegacy: true })

输出句柄

当命令输出超过 POWERSHELL_MCP_MAX_OUTPUT_SIZE:

  1. 输出被截断到指定的限制
  2. 完整输出保存到临时文件
  3. 响应包括访问完整输出的文件路径
  4. 如果自定义临时目录失败，则回退到系统临时目录

溢出响应示例：

{
  "success": true,
  "stdout": "...[truncated]...\n\n[Output truncated - exceeded 51200 bytes]\n[Full output saved to: C:\\temp\\powershell-mcp-stdout-2025-10-26.txt]",
  "overflow": true,
  "details": {
    "stdout": {
      "originalSize": 150000,
      "truncatedSize": 51200,
      "filePath": "C:\\temp\\powershell-mcp-stdout-2025-10-26.txt"
    }
  }
}

响应格式

所有工具都返回JSON响应：

{
  "success": true,
  "stdout": "command output",
  "stderr": "error output if any",
  "command": "executed command",
  "shell": "PowerShell 7"
}

使用示例

检查系统进程

Get-Process | Sort-Object CPU -Descending | Select-Object -First 10

管理服务

# List all services
Get-Service

# Start a service (requires admin)
Start-Service -Name "wuauserv"

使用文件

# Get files modified in last 24 hours
Get-ChildItem -Recurse | Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-1) }

网络信息

# Get network adapters
Get-NetAdapter | Select-Object Name, Status, LinkSpeed

# Test connectivity
Test-NetConnection -ComputerName google.com -Port 443

安全考虑

此MCP服务器以与Node.js进程相同的权限执行任意PowerShell命令。

最佳实践：

  • 仅在开发环境或受信任的环境中使用
  • 以最低权限运行
  • 尽可能在执行前检查命令
  • 使用适当的执行策略
  • 监控后台进程

需求

  • Node.js>=16.0.0
  • Windows 10/11或Windows服务器
  • PowerShell 7+（推荐）或Windows PowerShell 5.1

故障排除

未找到PowerShell 7

如果您收到关于找不到pwsh.exe的错误：

  1. 从Microsoft应用商店安装PowerShell 7或https://github.com/PowerShell/PowerShell
  2. 或者配置为默认使用Windows PowerShell 5.1：
{
  "env": {
    "POWERSHELL_MCP_DEFAULT_SHELL": "powershell"
  }
}

执行策略错误

如果您看到执行策略错误：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

权限错误

某些命令需要管理员权限。如果需要，以管理员身份运行Claude Desktop。

发展

# Clone repository
git clone https://github.com/YourUsername/mcp-powershell.git
cd mcp-powershell

# Install dependencies
npm install

# Run locally
node index.js

许可证

麻省理工学院

作者

肖恩王子

贡献

欢迎在 GitHub.

致谢

灵感源自 bash-mcp 由tinywind。

相关 MCP