# Powershell_mcp

**Repository Path**: ezemeti/powershell_mcp

## Basic Information

- **Project Name**: Powershell_mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-04
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PowerShell MCP服务器

一个兼容PowerShell和CMD环境的MCP（Model Context Protocol）服务器实现，通过Stdio协议提供系统管理和命令执行功能。

## 功能特性

- 🔧 **跨平台兼容**: 支持Windows PowerShell 5.x、PowerShell Core 7.x+、CMD、Linux/macOS的bash
- 🚀 **自动检测**: 智能识别最佳可用shell环境
- 📊 **系统管理**: 获取系统信息、进程管理、环境变量操作
- 📁 **文件操作**: 文件和目录的CRUD操作
- 🔒 **安全执行**: 安全的命令执行环境，详细错误处理
- 🌐 **标准协议**: 完全兼容MCP标准，支持Stdio通信

## 快速开始

### 环境要求

- Node.js 16.0.0 或更高版本
- npm 或 yarn 包管理器
- 支持的操作系统：Windows、macOS、Linux

### 安装步骤

1. **克隆或下载项目**
   ```bash
   git clone <repository-url>
   cd PowerShellMCP
   ```

2. **安装依赖**
   ```bash
   npm install
   ```

3. **构建项目**
   ```bash
   npm run build
   ```

4. **启动服务器**
   ```bash
   npm start
   # 或者直接运行
   node build/index.js
   ```

## 使用方法

### 在Claude Desktop中使用

1. 编辑Claude Desktop配置文件：
   - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. 添加服务器配置：
   ```json
   {
     "mcpServers": {
       "powershell-mcp": {
         "command": "node",
         "args": ["e:/CustomizeTools/MCP/PowerShell/PowerShellMCP/build/index.js"],
         "env": {
           "NODE_ENV": "production"
         }
       }
     }
   }
   ```

3. 重启Claude Desktop即可使用

### 可用工具

#### 1. execute-command - 执行命令
执行任意命令，自动适配PowerShell、CMD或其他shell环境

**参数：**
- `command` (string): 要执行的命令字符串
- `shellType` (string, optional): 可选的shell类型（pwsh、powershell、cmd、bash）

**示例：**
```typescript
// 执行PowerShell命令
execute-command({
  command: "Get-Process | Where-Object {$_.CPU -gt 100} | Select-Object Name, CPU",
  shellType: "powershell"
})

// 执行CMD命令
execute-command({
  command: "dir /s /b",
  shellType: "cmd"
})

// 自动检测shell执行命令
execute-command({
  command: "ls -la"
})
```

#### 2. get-system-info - 获取系统信息
获取详细的系统信息，包括操作系统、硬件配置、网络接口等

**示例：**
```typescript
get-system-info({})
```

#### 3. file-operation - 文件操作
执行文件和目录操作，支持列出、读取、写入、删除和获取文件信息

**参数：**
- `operation` (enum): 操作类型 - "list", "read", "write", "delete", "info"
- `path` (string): 文件或目录路径
- `content` (string, optional): 写入内容（仅write操作需要）

**示例：**
```typescript
// 列出目录内容
file-operation({
  operation: "list",
  path: "C:/Users"
})

// 读取文件内容
file-operation({
  operation: "read",
  path: "C:/temp/config.txt"
})

// 写入文件
file-operation({
  operation: "write",
  path: "C:/temp/hello.txt",
  content: "Hello, PowerShell MCP!"
})
```

#### 4. get-processes - 进程管理
获取当前运行的进程列表，支持按名称过滤

**参数：**
- `filter` (string, optional): 进程名称过滤字符串

**示例：**
```typescript
// 获取所有进程
get-processes({})

// 过滤特定进程
get-processes({
  filter: "node"
})
```

#### 5. environment-variables - 环境变量管理
获取、设置或列出环境变量

**参数：**
- `action` (enum): 操作类型 - "get", "set", "list"
- `name` (string, optional): 变量名（get/set操作需要）
- `value` (string, optional): 变量值（set操作需要）

**示例：**
```typescript
// 列出所有环境变量
environment-variables({
  action: "list"
})

// 获取特定环境变量
environment-variables({
  action: "get",
  name: "PATH"
})

// 设置环境变量（临时）
environment-variables({
  action: "set",
  name: "MY_VAR",
  value: "my_value"
})
```

## 开发指南

### 项目结构
```
PowerShellMCP/
├── src/
│   └── index.ts          # 主服务器文件
├── build/                # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
├── README.md            # 项目文档
└── node_modules/        # 依赖包
```

### 开发命令

```bash
# 安装依赖
npm install

# 编译项目
npm run build

# 开发模式（监听文件变化）
npm run dev

# 启动服务器
npm start

# 测试命令
node build/index.js
```

### 调试技巧

1. **查看日志输出**：
   服务器启动时会输出调试信息到stderr，可以通过重定向查看：
   ```bash
   node build/index.js 2> debug.log
   ```

2. **测试工具调用**：
   可以使用MCP客户端测试工具调用，或直接在Claude Desktop中测试。

3. **错误处理**：
   所有工具都包含详细的错误处理，错误信息会返回给调用方。

## 兼容性说明

### Shell环境支持

| 环境类型 | 支持状态 | 检测优先级 |
|----------|----------|------------|
| PowerShell Core (pwsh) | ✅ 完全支持 | 1 |
| Windows PowerShell | ✅ 完全支持 | 2 |
| CMD命令提示符 | ✅ 完全支持 | 3 |
| Linux/macOS Bash | ✅ 完全支持 | 3 |

### 操作系统支持

| 操作系统 | 支持状态 | 备注 |
|----------|----------|------|
| Windows 10/11 | ✅ 完全支持 | 推荐使用PowerShell Core |
| Windows Server 2019+ | ✅ 完全支持 |  |
| macOS 10.15+ | ✅ 完全支持 |  |
| Linux Ubuntu 18.04+ | ✅ 完全支持 |  |
| Linux CentOS 7+ | ✅ 完全支持 |  |

## 安全考虑

1. **命令执行安全**：所有命令都在受控环境中执行
2. **路径验证**：文件操作前进行路径验证
3. **权限检查**：检查文件和目录的访问权限
4. **输入验证**：使用Zod进行参数验证
5. **错误隔离**：错误不会导致服务器崩溃

## 故障排除

### 常见问题

1. **权限错误**：
   - 确保有足够的文件系统权限
   - 在Windows上以管理员身份运行

2. **命令找不到**：
   - 检查PATH环境变量
   - 确认命令在系统PATH中

3. **构建失败**：
   - 确认Node.js版本符合要求
   - 删除node_modules重新安装

4. **连接问题**：
   - 检查Claude Desktop配置
   - 确认路径正确

### 调试信息

服务器启动时会输出以下调试信息：
```
PowerShell MCP服务器已启动
操作系统: Windows
Node.js版本: v24.2.0
服务器版本: 1.0.0
可用的工具: execute-command, get-system-info, file-operation, get-processes, environment-variables
```

## 贡献指南

欢迎提交Issue和Pull Request！

### 开发环境设置

1. Fork项目
2. 创建功能分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 创建Pull Request

## 许可证

ISC License

## 更新日志

### v1.0.0 (2024-12-19)
- 初始版本发布
- 支持PowerShell、CMD、Bash环境
- 提供系统管理、文件操作、进程管理、环境变量管理功能
- 完全兼容MCP标准协议

## 技术支持

如有问题，请通过以下方式联系：
- 提交GitHub Issue
- 查看项目文档
- 参考MCP官方文档：https://mcp-docs.cn/quickstart/server#node