PowerShell MCP Server

PowerShell MCP 服务

一个功能全面的 Model Context Protocol (MCP) 服务，让 Claude 及其他大模型应用能够在 Windows 系统上执行 PowerShell 命令、脚本并执行系统操作。

🌟 核心功能

• 🔧 PowerShell 执行：执行命令、运行脚本并创建新的 PowerShell 文件
• 🖥️ 系统监控：获取系统信息、监控进程、检查服务和磁盘空间
• 📁 文件操作：列出目录、获取文件信息，并通过模式匹配搜索文件
• ⚙️ 简单设置：一条命令即可完成安装，并自动配置 Claude Desktop
• 🛡️ 安全：安全的执行方式，具备完善的错误处理和会话管理

🛠️ 可用工具

PowerShell 工具

• execute-powershell - 执行 PowerShell 命令，可选工作目录
• execute-powershell-script - 带参数运行 PowerShell 脚本文件
• create-powershell-script - 创建新的 PowerShell 脚本

系统工具

• get-system-info - 全面的 Windows 系统信息
• get-process-list - 正在运行的进程及其 CPU/内存占用（可排序/可筛选）
• get-service-status - Windows 服务状态，支持筛选
• check-disk-space - 所有或指定驱动器的磁盘空间使用情况

文件工具

• list-directory - 增强的目录列表，支持筛选
• get-file-info - 详细的文件和目录元数据
• search-files - 支持模式匹配的递归文件搜索

📋 前置要求

• Windows 10/11 或 Windows Server 2016+
• Node.js 18.0.0 或更高版本
• PowerShell 5.1+ 或 PowerShell Core 7+
• Claude Desktop 应用

🚀 快速设置

方式 1：安全的自动化设置（推荐）

# Clone and setup with configuration management
git clone https://github.com/gunjanjp/powershell-mcp.git
cd powershell-mcp
complete-setup.bat

方式 2：配置恢复（如果你已有现有设置）

# If previous setup overwrote your existing configuration
node recovery.js status      # Check current state
node recovery.js scan        # Find backup configurations
node recovery.js restore 1   # Restore from backup
# OR
node recovery.js merge 1     # Merge backup with current config

方式 3：手动设置

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

# Install dependencies
npm install

# Safely add to existing configuration
node recovery.js add-powershell

# Restart Claude Desktop

📖 使用示例

向 Claude 提问：

• "执行 PowerShell：Get-Date"
• "检查我的系统信息"
• "显示 CPU 占用最高的 10 个进程"
• "我的磁盘空间使用情况如何？"
• "列出我的 Downloads 文件夹中的文件"
• "搜索 C:\Users 中所有 .txt 文件"
• "创建一个 PowerShell 脚本来备份我的 Documents 文件夹"

🔧 命令

服务命令

# Start the server
npm start

# Test components
npm test

# Run diagnostics
node diagnose.bat

# Start server directly  
node src/server.js

配置管理

# Check configuration status
node recovery.js status

# Find backup configurations
node recovery.js scan

# Safely add PowerShell server
node recovery.js add-powershell

# Restore from backup
node recovery.js restore <number>

# Merge configurations
node recovery.js merge <number>

# Show backup contents
node recovery.js show <number>

快速设置命令

# Complete setup with safety checks
complete-setup.bat

# Test server only
run-test.bat

📁 项目结构

powershell-mcp/
├── src/
│   ├── server.js           # Main MCP server (with stderr logging fix)
│   ├── tools/              # Tool implementations
│   │   ├── powershell-tools.js
│   │   ├── system-tools.js
│   │   └── file-tools.js
│   └── utils/              # Utility modules
│       └── system-utils.js
├── examples/               # Example PowerShell scripts
├── scripts/               # Setup utilities
├── test/                  # Test files
├── claude_desktop_config.json  # Claude Desktop configuration
├── setup.bat             # Automated setup script
├── diagnose.bat          # Diagnostic tool
├── test-server.js        # Component testing
└── README.md

⚙️ Claude Desktop 配置

本服务使用以下配置（由设置过程自动应用）：

{
  "mcpServers": {
    "powershell": {
      "command": "node",
      "args": ["D:/claude/claude-powershell-mcp/src/server.js"],
      "env": {}
    }
  }
}

配置文件位置：%APPDATA%\Claude\claude_desktop_config.json

🛡️ 安全特性

• 安全执行：出于安全考虑，使用 -ExecutionPolicy Bypass 和 -NoProfile
• 输入验证：所有输入均通过 Zod schema 验证
• 会话管理：PowerShell 会话使用完毕后会被正确释放
• 错误处理：完善的错误处理可防止系统问题
• 日志记录：所有操作均记录到 stderr（不会干扰 JSON-RPC）

🐛 故障排查

服务无法启动

# Check Node.js version (need 18+)
node --version

# Check dependencies
npm install

# Test components
node test-server.js

Claude Desktop 集成问题

# Run setup again
setup.bat

# Check configuration
type "%APPDATA%\Claude\claude_desktop_config.json"

# Restart Claude Desktop completely

PowerShell 执行问题

# Test PowerShell
powershell -Command "Get-Date"

# Check execution policy
Get-ExecutionPolicy

# Run diagnostics
node diagnose.bat

🔄 最近更新（v1.1.2）

配置管理改进

• ✅ 安全的配置管理 - 不再覆盖现有配置
• ✅ 自动备份 - 在任何配置更改前创建备份
• ✅ 配置恢复 - 提供查找并恢复先前配置的工具
• ✅ 合并能力 - 智能合并多个 MCP 服务配置
• ✅ 交互式恢复 - 逐步进行的配置恢复流程

此前的修复（v1.1.1）

• ✅ 修复了 Claude Desktop 的 JSON 解析错误 - 将 console.log 改为 console.error（stderr）
• ✅ 清理了项目结构 - 移除了多余的服务器文件
• ✅ 简化了设置 - 单脚本设置流程
• ✅ 完善的错误处理 - 增强了日志记录和错误管理

🤝 贡献

1. Fork 该仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改并测试：npm test
4. 提交：git commit -am 'Add feature'
5. 推送：git push origin feature-name
6. 提交 pull request

📄 许可证

MIT License - 详见 LICENSE 文件。

🔗 链接

• GitHub 仓库
• Model Context Protocol
• Claude Desktop

---

用 ❤️ 为 Claude 和 PowerShell 社区打造

⚠️ 重要：此工具提供对 PowerShell 命令的直接访问。请负责任地使用，并注意安全影响。