mcp-powershell-server

hypo69/mcp-powershell-server

3.1

If you are the rightful owner of mcp-powershell-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP PowerShell Server is a secure implementation of the Model Context Protocol (MCP) for executing PowerShell scripts.

MCP PowerShell Server

Сервер MCP (Model Context Protocol) для выполнения PowerShell скриптов, поддерживающий как HTTP, так и STDIO режимы работы.

Описание

MCP PowerShell Server позволяет ИИ-ассистентам выполнять PowerShell команды и скрипты через стандартизированный протокол MCP. Сервер поддерживает два режима работы:

  • STDIO режим: Для интеграции с gemini-cli и другими локальными MCP-клиентами.
  • HTTP режим: Для веб-приложений и интеграции по сети через REST API.

Какой режим выбрать: HTTP или STDIO?

Выбор между mcp-powershell-http.ps1 и mcp-powershell-stdio.ps1 зависит от того, как и откуда клиентское приложение будет взаимодействовать с сервером.

  • mcp-powershell-http.ps1 (HTTP режим) работает как официант в ресторане. Он принимает заказы (HTTP-запросы) от любого клиента в сети, передает их на "кухню" (PowerShell) и возвращает готовый результат (HTTP-ответ).
  • mcp-powershell-stdio.ps1 (STDIO режим) работает как личный помощник на кухне. Он получает задания напрямую (через стандартный ввод stdin) от управляющего процесса (например, gemini-cli), который сам его запустил, и немедленно отдает результат обратно (через стандартный вывод stdout).

Когда использовать HTTP режим

Вам следует выбрать HTTP, если требуется сетевое взаимодействие.

  • Удаленное управление: Клиентское приложение находится на другом компьютере.
  • Веб-интеграция: Необходимо вызывать PowerShell-скрипты из веб-приложения, панели администратора или через AJAX-запросы.
  • Микросервисная архитектура: Другие сервисы в вашей сети должны взаимодействовать с PowerShell.
  • Простое тестирование: Вы хотите использовать инструменты вроде curl, Postman или Invoke-RestMethod для отправки команд.

Простыми словами: выбирайте HTTP, если между клиентом и сервером есть сеть.

Когда использовать STDIO режим

Этот режим идеально подходит для локальной и безопасной интеграции.

  • Основной сценарий — Gemini CLI: Инструмент gemini-cli сам запускает mcp-powershell-stdio.ps1 как дочерний процесс и общается с ним напрямую через стандартные потоки ввода-вывода.
  • Интеграция с другими локальными приложениями: Ваша программа на Python, Node.js или другом языке может запустить сервер и управлять им, не открывая сетевые порты.
  • Повышенная безопасность: Поскольку сетевые порты не открываются, этот способ по умолчанию более безопасен.

Простыми словами: выбирайте STDIO, если клиент и сервер находятся на одной машине, и клиент сам запускает сервер.

Сравнительная таблица

ХарактеристикаHTTP режим (mcp-powershell-http.ps1)STDIO режим (mcp-powershell-stdio.ps1)
Основной сценарийСетевое взаимодействие, веб-APIЛокальная интеграция с CLI-инструментами
Тип связиКлиент-сервер по сети (TCP/IP)Межпроцессное взаимодействие (IPC)
РасположениеКлиент и сервер могут быть на разных машинахКлиент и сервер должны быть на одной машине
БезопасностьТребует внимания (доступ к порту, файрвол)Более безопасен по умолчанию (нет открытых портов)
Типичные клиентыcurl, Postman, веб-приложения, удаленные скриптыgemini-cli, локальные приложения-обертки

Особенности

  • ✅ Поддержка MCP протокола версии 2024-11-05
  • ✅ Два режима работы: STDIO и HTTP
  • ✅ Изоляция выполнения скриптов в отдельных PowerShell процессах
  • ✅ Настраиваемые тайм-ауты выполнения
  • ✅ Детальное логирование всех операций
  • ✅ Обработка ошибок и предупреждений PowerShell
  • ✅ Поддержка параметров скриптов
  • ✅ Настраиваемая рабочая директория
  • ✅ Автоматические launcher'ы для упрощения запуска

Системные требования

  • PowerShell 7.0 или новее
  • Windows 10/11 или Windows Server 2019+
  • .NET 6.0 или новее

Структура проекта

mcp-powershell-server/
├── src/
│   ├── clients/           # Клиентские приложения
│   │   ├── node/         # Node.js клиент
│   │   ├── powershell/   # PowerShell клиент
│   │   └── python/       # Python клиент
│   └── servers/          # Серверные компоненты
│       ├── mcp-powershell-stdio.ps1   # STDIO версия сервера
│       ├── mcp-powershell-http.ps1    # HTTP версия сервера
│       ├── test-mcp.ps1               # Тестовый сервер
│       └── config.json                # Файл конфигурации
├── docs/                 # Документация
├── README.md            # Этот файл
└── how-to-use.md        # Подробное руководство

Быстрый старт

STDIO режим (для gemini-cli)

  1. Запуск сервера:

    .\src\servers\mcp-powershell-stdio.ps1

  2. Тестирование:

    .\src\servers\test-mcp.ps1

HTTP режим

  1. Базовый запуск:

    .\src\servers\mcp-powershell-http.ps1

  2. С настраиваемыми параметрами:

    .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"

  3. С файлом конфигурации:

    .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Доступные MCP инструменты

run-script

Выполняет PowerShell скрипт с заданными параметрами.

Параметры:

  • script (обязательный) - PowerShell код для выполнения
  • parameters (опциональный) - Хеш-таблица параметров
  • workingDirectory (опциональный) - Рабочая директория
  • timeoutSeconds (опциональный) - Тайм-аут выполнения (1-3600 сек)

Пример использования через MCP:

{
  "name": "run-script",
  "arguments": {
    "script": "Get-Process | Select-Object -First 5 | Format-Table",
    "workingDirectory": "C:\\",
    "timeoutSeconds": 30
  }
}

Конфигурация

Сервер поддерживает конфигурацию через файл config.json:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Tools\\"
  ],
  "Security": {
    "EnableScriptValidation": true,
    "BlockDangerousCommands": true,
    "RestrictedCommands": [
      "Remove-Item",
      "Format-Volume",
      "Stop-Computer",
      "Restart-Computer"
    ]
  }
}

Безопасность

  • Выполнение скриптов происходит в изолированных PowerShell процессах
  • Поддержка списка запрещенных команд
  • Ограничение по времени выполнения
  • Логирование всех выполняемых команд
  • Возможность ограничения доступных путей

Логирование

  • STDIO режим: Логи записываются в %TEMP%\mcp-powershell-server.log
  • HTTP режим: Логи выводятся в консоль с цветовой индикацией

Уровни логирования: DEBUG, INFO, WARNING, ERROR

Интеграция с ИИ-ассистентами

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Покажи первые 5 процессов в системе"

Другие MCP-клиенты

Сервер совместим со всеми клиентами, поддерживающими MCP протокол 2024-11-05.

Устранение неполадок

Общие проблемы

  1. Порт занят: Измените порт в конфигурации или остановите процесс, использующий порт
  2. Права доступа: Запуск на привилегированных портах (<1024) требует прав администратора
  3. Кодировка: Убедитесь, что PowerShell настроен на UTF-8
  4. Версия PowerShell: Требуется PowerShell 7+

Диагностика

Проверьте логи сервера для диагностики проблем:

Get-Content "$env:TEMP\mcp-powershell-server.log" -Tail 20

Разработка и расширение

Сервер легко расширяется новыми MCP инструментами. См. how-to-use.md для подробных инструкций по разработке.

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

Поддержка

  • Создайте Issue в GitHub репозитории
  • Проверьте документацию в how-to-use.md
  • Ознакомьтесь с примерами использования

Версии

  • 1.0.0 - Начальная версия с поддержкой STDIO и HTTP режимов