PowerShell MCP Server

PowerShell MCP サーバー

Claude やその他の LLM アプリケーションが Windows システム上で PowerShell コマンドやスクリプトを実行し、システム操作を行えるようにする包括的な Model Context Protocol (MCP) サーバーです。

🌟 主な機能

• 🔧 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 個のプロセスを表示して」
• 「ディスク容量の使用状況は?」
• 「ダウンロードフォルダ内のファイルを一覧表示して」
• 「C:\Users 内のすべての .txt ファイルを検索して」
• 「ドキュメントフォルダをバックアップする PowerShell スクリプトを作成して」

🔧 コマンド

サーバーコマンド

# 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 スキーマで検証
• セッション管理: 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 つのスクリプトによるセットアッププロセス
• ✅ 適切なエラー処理 - ログ記録とエラー管理を強化

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します: git checkout -b feature-name
3. 変更を加えてテストします: npm test
4. コミットします: git commit -am 'Add feature'
5. プッシュします: git push origin feature-name
6. プルリクエストを送信します

📄 ライセンス

MIT ライセンス - 詳細は LICENSE ファイルをご覧ください。

🔗 リンク

• GitHub リポジトリ
• Model Context Protocol
• Claude Desktop

---

Claude と PowerShell コミュニティのために ❤️ を込めて制作

⚠️ 重要: このツールは PowerShell コマンドへの直接アクセスを提供します。責任を持って使用し、セキュリティ上の影響に注意してください。