winrm-mcp

Небольшой MCP-сервер для выполнения команд PowerShell и CMD на хостах Windows через WinRM. Он заимствует идеи выполнения WinRM из ssh-winrm-mcp, добавляет сфокусированную многопоточную инвентаризацию и исключает SSH, постоянные сеансы, задания, группы команд и передачу файлов.

Инструменты

• winrm_test — проверка подлинности и связи.

• winrm_execute_powershell — выполнение PowerShell.

• winrm_execute_cmd — выполнение CMD.

• winrm_inventory_status, winrm_inventory_init, winrm_inventory_validate — управление файлами инвентаризации.

• winrm_host_list, winrm_host_get, winrm_host_save, winrm_host_update, winrm_host_delete — управление переиспользуемыми хостами.

Каждый инструмент принимает необязательный объект connection. Значения в нем переопределяют переменные окружения процесса:

{
  "host": "192.168.1.50",
  "username": "Administrator",
  "password_env": "MY_WINRM_PASSWORD",
  "auth": "ntlm",
  "ssl": true,
  "cert_validation": false
}

ssl выбирает HTTPS (обычно порт 5986) вместо HTTP (обычно порт 5985). cert_validation=false требуется для самозаверяющих HTTPS-прослушивателей, но его следует использовать только для доверенных хостов.

Поддерживаемые поля подключения: host, username, password, password_env, port, ssl, auth, cert_validation, encryption, path, connect_timeout, read_timeout и operation_timeout.

Related MCP server: Win MCP Server

Многопоточная инвентаризация

Хосты могут храниться в одной из областей инвентаризации:

• user (по умолчанию): ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json в Linux/macOS или соответствующее расположение %APPDATA% в Windows.

• project: .winrm-mcp/inventory.json в текущем рабочем каталоге.

Выберите процесс по умолчанию с помощью WINRM_MCP_INVENTORY_SCOPE=user или WINRM_MCP_INVENTORY_SCOPE=project. Каждый инструмент инвентаризации и хостинга также принимает явный scope, а инструменты выполнения — inventory_scope. Область проекта использует WINRM_MCP_PROJECT_DIR, затем логический PWD загрузчика, затем рабочий каталог процесса. Он отказывается от временных путей deepagents_server_* вместо того, чтобы молча сохранять одноразовые данные инвентаризации. Установите WINRM_MCP_PROJECT_DIR, если рабочий каталог загрузчика не является корнем проекта. Полностью настраиваемый файл поддерживается через WINRM_MCP_INVENTORY_FILE; он используется, когда вызов явно не выбирает область.

Создайте инвентаризацию проекта и сохраните два хоста:

winrm_inventory_init(scope="project")

winrm_host_save(
  name="epv1",
  scope="project",
  settings={
    "host": "10.0.110.50",
    "username": "Administrator",
    "password_env": "EPV1_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

winrm_host_save(
  name="epv2",
  scope="project",
  settings={
    "host": "10.0.110.51",
    "username": "Administrator",
    "password_env": "EPV2_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

Используйте сохраненный хост по имени:

winrm_test(saved_host="epv1", inventory_scope="project")
winrm_execute_powershell(saved_host="epv1", inventory_scope="project", command="hostname")
winrm_execute_cmd(saved_host="epv2", inventory_scope="project", command="whoami")

Необязательный объект connection переопределяет поля сохраненного хоста для этого вызова. Запись в инвентаризацию атомарна, а файл инвентаризации доступен только текущему пользователю (0600) в Unix-подобных системах. Встроенные пароли поддерживаются, но хранятся в виде открытого текста в этом защищенном JSON-файле; предпочтительнее использовать password_env.

Опустите connection, если переопределения не нужны. Для совместимости с агентами, которые сериализуют необязательное значение как текст, connection="None", connection="null" и пустая строка подключения рассматриваются как JSON null.

DeepAgents

DeepAgents может запускать сервер напрямую с GitHub, поэтому локальная проверка не требуется. Добавьте следующую запись в файл DeepAgents .deepagents/.mcp.json:

{
  "winrm": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "tool",
      "run",
      "--with",
      "mcp>=1.28,<2",
      "--from",
      "git+https://github.com/bigbatmanorg/winrm-mcp.git",
      "winrm-mcp"
    ],
    "env": {
      "WINRM_MCP_HOST": "192.168.1.50",
      "WINRM_MCP_USERNAME": "Administrator",
      "WINRM_MCP_PASSWORD": "YOUR_SECRET",
      "WINRM_MCP_PORT": "5986",
      "WINRM_MCP_AUTH": "ntlm",
      "WINRM_MCP_SSL": "true",
      "WINRM_MCP_CERT_VALIDATION": "false",
      "WINRM_MCP_INVENTORY_SCOPE": "project",
      "WINRM_MCP_PROJECT_DIR": "${PWD}",
      "WINRM_MCP_CONNECT_TIMEOUT": "30",
      "WINRM_MCP_READ_TIMEOUT": "60",
      "WINRM_MCP_OPERATION_TIMEOUT": "30"
    }
  }
}

Для воспроизводимых установок закрепите репозиторий за тегом выпуска или коммитом:

"git+https://github.com/bigbatmanorg/winrm-mcp.git@YOUR_TAG_OR_COMMIT"

В примере используется HTTPS с отключенной проверкой сертификата для доверенного хостинга разработки с самозаверяющим сертификатом. Оставьте WINRM_MCP_CERT_VALIDATION=true, если сертификат прослушивателя доверенный. Не сохраняйте настоящий пароль в системе контроля версий; используйте обычный рабочий процесс внедрения секретов DeepAgents для WINRM_MCP_PASSWORD. DeepAgents разворачивает ${PWD} перед запуском MCP-сервера. Замените его абсолютным путем, если DeepAgents запускается не из корня проекта.

Установка и запуск

uv sync --extra dev
uv run pytest
uv run winrm-mcp

Транспорт по умолчанию — stdio. Конфигурация клиента может предоставлять стабильные настройки подключения по умолчанию без указания учетных данных в каждом вызове инструмента:

{
  "servers": {
    "winrm": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/home/toor/projects/winrm-mcp", "run", "winrm-mcp"],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD_ENV": "MY_WINRM_PASSWORD",
        "MY_WINRM_PASSWORD": "replace-me",
        "WINRM_MCP_AUTH": "ntlm",
        "WINRM_MCP_SSL": "true",
        "WINRM_MCP_CERT_VALIDATION": "false"
      }
    }
  }
}

Доступные переменные окружения по умолчанию соответствуют полям подключения и используют префикс WINRM_MCP_. Параметры сервера: WINRM_MCP_TRANSPORT, WINRM_MCP_SERVER_HOST и WINRM_MCP_SERVER_PORT. Параметры инвентаризации: WINRM_MCP_INVENTORY_SCOPE, WINRM_MCP_PROJECT_DIR и WINRM_MCP_INVENTORY_FILE.

Для поддержки Kerberos или CredSSP установите соответствующий дополнительный пакет:

uv sync --extra kerberos
uv sync --extra credssp