winrm-mcp

WinRM을 통해 Windows 호스트에서 PowerShell 및 CMD 명령을 실행하기 위한 의도적으로 작은 MCP 서버입니다. ssh-winrm-mcp의 WinRM 실행 아이디어를 가져와 다중 호스트 인벤토리에 초점을 맞추고, 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) 중에서 선택합니다. 자체 서명된 HTTPS 리스너에는 cert_validation=false가 필요하지만 신뢰할 수 있는 호스트에만 사용해야 합니다.

지원되는 연결 필드는 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(기본값): Linux/macOS에서는 ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json, Windows에서는 해당 %APPDATA% 위치.

• 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 객체는 해당 호출에 대해 저장된 호스트의 필드를 재정의합니다. 인벤토리 쓰기는 원자적이며, 인벤토리 파일은 Unix 계열 시스템에서 현재 사용자(0600)로 제한됩니다. 인라인 암호는 지원되지만 보호된 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를 유지하세요. 실제 암호를 소스 제어에 커밋하지 마세요. WINRM_MCP_PASSWORD에는 일반적인 DeepAgents 비밀 주입 워크플로를 사용하세요. DeepAgents는 MCP 서버를 시작하기 전에 ${PWD}를 확장합니다. 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