Skip to main content
Glama

winrm-mcp

A focused MCP server for running PowerShell and CMD commands on Windows hosts over WinRM, with a multi-host inventory, parallel execution across tagged hosts, sandboxed file transfer and an operator-controlled security policy. It leaves out SSH, persistent sessions, jobs and command groups (see ssh-winrm-mcp for those).

  • Accurate exit codes, including PowerShell exit N; timed-out commands are stopped on the remote host.

  • output_format="json" returns PowerShell objects as parsed JSON instead of formatted text.

  • Every tool declares MCP annotations so clients can ask before running remote commands.

Install in your agent

Install in VS Code Install in VS Code Insiders Install in Cursor

It works with any MCP client that can start a stdio command. It needs uv. uvx fetches the pinned release, so no clone or virtualenv is needed. Pick your agent below.

Variable

Meaning

Example

WINRM_MCP_HOST

Default Windows host

192.168.1.50

WINRM_MCP_USERNAME

Default user

Administrator

WINRM_MCP_PASSWORD

Default password

your-password

All three are optional defaults. Without them, pass the connection in each tool call or use the multi-host inventory. Other defaults use the same WINRM_MCP_ prefix: WINRM_MCP_AUTH (ntlm), WINRM_MCP_SSL, WINRM_MCP_PORT, WINRM_MCP_CERT_VALIDATION. See Install and run.

The VS Code buttons ask for each value, keeping secrets out of files. The Cursor button writes placeholders: edit them in ~/.cursor/mcp.json afterwards. Elsewhere, replace the example values.

claude mcp add winrm -s user -e WINRM_MCP_HOST=192.168.1.50 -e WINRM_MCP_USERNAME=Administrator -e WINRM_MCP_PASSWORD=your-password -- uvx --from git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0 winrm-mcp

Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Use the button above, or add this to .vscode/mcp.json (workspace) or to the user mcp.json (command MCP: Open User Configuration):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "winrm_mcp_host",
      "description": "Default Windows host",
      "password": false
    },
    {
      "type": "promptString",
      "id": "winrm_mcp_username",
      "description": "Default user",
      "password": false
    },
    {
      "type": "promptString",
      "id": "winrm_mcp_password",
      "description": "Default password",
      "password": true
    }
  ],
  "servers": {
    "winrm": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "${input:winrm_mcp_host}",
        "WINRM_MCP_USERNAME": "${input:winrm_mcp_username}",
        "WINRM_MCP_PASSWORD": "${input:winrm_mcp_password}"
      }
    }
  }
}

Use the button above, or add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}
codex mcp add winrm --env WINRM_MCP_HOST=192.168.1.50 --env WINRM_MCP_USERNAME=Administrator --env WINRM_MCP_PASSWORD=your-password -- uvx --from git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0 winrm-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.winrm]
command = "uvx"
args = ["--from", "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0", "winrm-mcp"]
env = { WINRM_MCP_HOST = "192.168.1.50", WINRM_MCP_USERNAME = "Administrator", WINRM_MCP_PASSWORD = "your-password" }

Add this to ~/.gemini/settings.json (or to .gemini/settings.json in a project):

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Deep Agents CLI: add this to ~/.deepagents/.mcp.json (all projects) or to .mcp.json in a project. ${VAR} values are read from your shell or ~/.deepagents/.env, so secrets stay out of the file.

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "${WINRM_MCP_HOST}",
        "WINRM_MCP_USERNAME": "${WINRM_MCP_USERNAME}",
        "WINRM_MCP_PASSWORD": "${WINRM_MCP_PASSWORD}"
      }
    }
  }
}

Python library (pip install deepagents langchain-mcp-adapters):

import asyncio
import os

from deepagents import create_deep_agent
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "winrm": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["--from", "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0", "winrm-mcp"],
        "env": {
            "WINRM_MCP_HOST": os.environ["WINRM_MCP_HOST"],
            "WINRM_MCP_USERNAME": os.environ["WINRM_MCP_USERNAME"],
            "WINRM_MCP_PASSWORD": os.environ["WINRM_MCP_PASSWORD"],
        },
    }
})


async def main():
    tools = await client.get_tools()
    agent = create_deep_agent(model="anthropic:claude-sonnet-5-5", tools=tools)
    result = await agent.ainvoke({"messages": [{"role": "user", "content": "What can you do?"}]})
    print(result["messages"][-1].content)


asyncio.run(main())

Save this as agent.yaml, then run docker agent run agent.yaml:

agents:
  root:
    model: anthropic/claude-sonnet-5-5
    description: Assistant with the winrm MCP tools
    instruction: Use the winrm tools to answer the user's requests.
    toolsets:
      - type: mcp
        command: uvx
        args:
          - "--from"
          - "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0"
          - "winrm-mcp"
        env:
          WINRM_MCP_HOST: "192.168.1.50"
          WINRM_MCP_USERNAME: "Administrator"
          WINRM_MCP_PASSWORD: "your-password"

Add this to ~/.hermes/config.yaml, then run /reload-mcp in a chat:

mcp_servers:
  winrm:
    command: uvx
    args: ["--from", "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0", "winrm-mcp"]
    env:
      WINRM_MCP_HOST: "192.168.1.50"
      WINRM_MCP_USERNAME: "Administrator"
      WINRM_MCP_PASSWORD: "your-password"

MCP Servers → Configure (cline_mcp_settings.json / mcp_settings.json):

{
  "mcpServers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Add this to settings.json:

{
  "context_servers": {
    "winrm": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Add this to opencode.json (project) or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "winrm": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0",
        "winrm-mcp"
      ],
      "environment": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD": "your-password"
      },
      "enabled": true
    }
  }
}

Run goose configure → Add Extension → Command-line Extension, with the command uvx --from git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0 winrm-mcp. Or add this to ~/.config/goose/config.yaml:

extensions:
  winrm:
    type: stdio
    enabled: true
    cmd: uvx
    args: ["--from", "git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0", "winrm-mcp"]
    envs:
      WINRM_MCP_HOST: "192.168.1.50"
      WINRM_MCP_USERNAME: "Administrator"
      WINRM_MCP_PASSWORD: "your-password"

Most clients take the standard mcpServers JSON shown for Claude Desktop. Some use servers instead.

To install once instead of fetching on each start:

uv tool install git+https://github.com/bigbatmanorg/winrm-mcp.git@v0.3.0

then use "command": "winrm-mcp", "args": [].

From a checkout: "command": "uv", "args": ["run", "--directory", "/abs/path/winrm-mcp", "winrm-mcp"].

Related MCP server: Win MCP Server

Tools

  • winrm_test — verify authentication and connectivity; reports whether the account is a local administrator.

  • winrm_execute_powershell — execute PowerShell (output_format="json" for structured results).

  • winrm_execute_cmd — execute CMD; env sets real process environment variables.

  • winrm_execute_many — run one command on several saved hosts (by name or tag) in parallel, one result per host.

  • winrm_upload, winrm_download — copy files, confined to WINRM_MCP_LOCAL_ROOT (disabled unless set).

  • winrm_policy — show the version and the active security policy.

  • winrm_inventory_status, winrm_inventory_init, winrm_inventory_validate — manage inventory files.

  • winrm_host_list, winrm_host_get, winrm_host_save, winrm_host_update, winrm_host_delete — manage reusable hosts.

Each tool accepts an optional connection object. Values in it override the process environment:

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

ssl chooses HTTPS (normally port 5986) versus HTTP (normally port 5985). cert_validation=false is needed for self-signed HTTPS listeners, but should only be used for trusted hosts.

Supported connection fields are host, username, password, password_env, port, ssl, auth (ntlm, negotiate, kerberos, basic, credssp, certificate), cert_validation, encryption, path, connect_timeout, read_timeout, operation_timeout, certificate_pem and certificate_key_pem (file paths for certificate auth over HTTPS), and tags (a list of labels for winrm_host_list(tag=...) and winrm_execute_many(tag=...)).

Security model

Commands run with the remote account's full rights, and tool arguments come from an AI agent that untrusted content (web pages, files, command output) can steer. The operator limits what the agent can reach:

Setting

Default

Effect

WINRM_MCP_ALLOWED_HOSTS

any

Comma-separated glob patterns (*.lab.example,10.0.110.*); other hosts are refused, saved or not.

WINRM_MCP_ALLOW_ADHOC

true

false allows only saved hosts; per-call connection may then only change timeouts.

WINRM_MCP_SECRET_ENV_PATTERNS

*PASSWORD*,*PASSWD*,*_PASS

password_env may only read matching variables, so an agent cannot send e.g. AWS_SECRET_ACCESS_KEY to a host it controls.

WINRM_MCP_ALLOW_INSECURE_BASIC

false

Basic auth over plain HTTP sends the password in cleartext and is refused unless enabled. NTLM/Kerberos over HTTP use message encryption and are allowed.

WINRM_MCP_LOCAL_ROOT

unset

Enables winrm_upload/winrm_download, confined to this directory.

Multi-host inventory

Hosts can be stored in either inventory scope:

  • user (default): ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json on Linux/macOS, or the matching %APPDATA% location on Windows.

  • project: .winrm-mcp/inventory.json under the current working directory.

Choose the process default with WINRM_MCP_INVENTORY_SCOPE=user or WINRM_MCP_INVENTORY_SCOPE=project. Every inventory and host tool also accepts an explicit scope, and execution tools accept inventory_scope. Project scope uses WINRM_MCP_PROJECT_DIR, then the launcher's logical PWD, then the process working directory. It refuses temporary deepagents_server_* paths instead of silently saving disposable inventory data. Set WINRM_MCP_PROJECT_DIR when the launcher working directory is not the desired project root. A fully custom file is supported through WINRM_MCP_INVENTORY_FILE; it is used when a call does not explicitly select a scope.

Create a project inventory and save two hosts:

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
  }
)

Use a saved host by name:

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")

The optional connection object overrides fields from the saved host for that call. Inventory writes are atomic, and the inventory file is restricted to the current user (0600) on Unix-like systems. Inline passwords are supported but stored as plaintext in that protected JSON file; prefer password_env.

Omit connection when no overrides are needed. For compatibility with agents that serialize an optional value as text, connection="None", connection="null", and an empty connection string are treated as JSON null.

Install and run

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

The default transport is stdio. A client configuration can supply stable connection defaults without putting credentials in every tool call:

{
  "servers": {
    "winrm": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/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"
      }
    }
  }
}

Available environment defaults correspond to the connection fields and use the WINRM_MCP_ prefix. Server settings are WINRM_MCP_TRANSPORT, WINRM_MCP_SERVER_HOST, and WINRM_MCP_SERVER_PORT. Inventory settings are WINRM_MCP_INVENTORY_SCOPE, WINRM_MCP_PROJECT_DIR, and WINRM_MCP_INVENTORY_FILE.

Testing

uv sync --extra dev
uv run pytest                                  # offline unit tests
WINRM_LIVE=1 uv run pytest tests/live -v       # live tests over MCP stdio against a Windows host

Live tests read WINRM_TEST_HOST, WINRM_TEST_ADMIN_USER/WINRM_TEST_ADMIN_PASSWORD (a local administrator) and WINRM_TEST_USER/WINRM_TEST_USER_PASSWORD (a member of Remote Management Users), for example from a gitignored .env.

For Kerberos or CredSSP support, install the matching optional extra:

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

Available Tools

15 tools
winrm_downloadA
Destructive

Copy a file from the Windows host to WINRM_MCP_LOCAL_ROOT/local_path (file transfer is disabled unless the operator sets it). Existing local files are kept unless overwrite=true.

Inputs: local_path (required), remote_path (required), overwrite, connection, +2 more. Returns: object

winrm_execute_cmdA
Destructive

Execute a CMD command over WinRM and return stdout, stderr, and exit code. env sets real process environment variables (usable as %NAME%). On timeout the remote process is terminated.

Inputs: command (required), cwd, env, timeout, +4 more. Returns: object

winrm_execute_manyB
Destructive

Run one command on several saved hosts (listed by name and/or selected by tag) in parallel. Returns one result or error per host, so one unreachable host does not hide the others.

Inputs: command (required), tag, shell, timeout, +5 more. Returns: object

winrm_execute_powershellA
Destructive

Execute PowerShell over WinRM and return stdout, stderr (error/warning/verbose streams) and the exit code, including exit N. On timeout the remote command is stopped. output_format='json' converts the output objects with ConvertTo-Json and returns them parsed in data.

Inputs: command (required), cwd, env, timeout, +5 more. Returns: object

winrm_host_deleteC
DestructiveIdempotent

Delete a saved WinRM host.

Inputs: name (required), scope. Returns: object

winrm_host_getB
Read-only

Get one saved WinRM host with its password redacted.

Inputs: name (required), scope. Returns: object

winrm_host_listB
Read-only

List saved WinRM hosts with passwords redacted; optionally only hosts carrying a tag.

Inputs: tag, scope. Returns: object

winrm_host_saveB
Idempotent

Save a WinRM host in the project or user inventory. Prefer password_env over password; tags (a list of strings) group hosts for winrm_execute_many.

Inputs: name (required), settings (required), scope, overwrite. Returns: object

winrm_host_updateB
Idempotent

Update selected settings on a saved host; remove optional values with remove_fields.

Inputs: name (required), changes (required), scope, remove_fields. Returns: object

winrm_inventory_initB
Idempotent

Create an empty project or user inventory without replacing existing data by default.

Inputs: scope, overwrite. Returns: object

winrm_inventory_statusB
Read-only

Show the project or user inventory path, existence, and saved host count.

Inputs: scope. Returns: object

winrm_inventory_validateB
Read-only

Validate an inventory file and every saved WinRM host.

Inputs: scope. Returns: object

winrm_policyA
Read-only

Show the server version and the operator's security policy: allowed hosts, whether ad-hoc connections are allowed, which environment variables password_env may read, and whether file transfer is enabled.

Inputs: no named parameters. Returns: object

winrm_testB
Read-only

Test a WinRM connection with a harmless PowerShell marker command; reports whether the account is a local administrator.

Inputs: timeout, connection, saved_host, inventory_scope. Returns: object

winrm_uploadA
Destructive

Copy a local file to the Windows host. local_path is relative to WINRM_MCP_LOCAL_ROOT (file transfer is disabled unless the operator sets it); remote_path is a full Windows path.

Inputs: local_path (required), remote_path (required), connection, saved_host, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct resource and action: inventory management, host CRUD, connection testing, policy inspection, command execution, and file transfer are all separated. The only mild similarity is between winrm_test and winrm_inventory_validate, but their descriptions make the distinction clear: one tests a single connection, the other validates inventory and saved hosts.

    Naming Consistency4/5

    All tools use a consistent winrm_ prefix and snake_case, mostly following a resource_action pattern such as winrm_host_list or winrm_inventory_validate. A few names like winrm_test and winrm_policy are less structurally explicit, but they remain predictable and readable.

    Tool Count5/5

    Fifteen tools is well within a reasonable range for a WinRM management server and each tool appears to earn its place. Inventory, host lifecycle, execution, testing, policy, and transfer operations are all meaningfully separated without obvious filler.

    Completeness4/5

    The surface covers host CRUD, inventory initialization/status/validation, connection testing, policy inspection, PowerShell/CMD execution, multi-host execution, and file upload/download. Minor gaps remain, such as no explicit inventory deletion or richer inventory editing, but core workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to securely manage and execute commands on remote Windows servers via WinRM, including PowerShell execution, system information retrieval, and service management.
      6
      13 PyPI
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables executing commands and transferring files over SSH on multiple hosts concurrently, with auto-discovery from SSH config and support for various authentication methods.
      3
      6 npm
      MIT