winrm-mcp
Summary: winrm-mcp lets an AI agent run PowerShell/CMD commands on Windows hosts over WinRM, manage a multi-host inventory, and move files under operator-controlled security limits.
Run PowerShell remotely (
winrm_execute_powershell), with accurate exit codes, timeouts that stop the remote command, and optionaloutput_format="json"for parsed objects.Run CMD commands remotely (
winrm_execute_cmd) with real process environment variables.Test connectivity/authentication on a host and see whether the account is a local administrator (
winrm_test).Execute one command across multiple saved hosts in parallel, by name or tag (
winrm_execute_many), getting per-host results/errors.Save, list, get, update, and delete reusable WinRM hosts, optionally tagged (
winrm_host_*), with passwords redacted in outputs.Create, inspect, and validate project- or user-scoped inventories (
winrm_inventory_*).Upload and download files, confined to a local root and disabled unless the operator enables it (
winrm_upload,winrm_download).Inspect the server version and active security policy—allowed hosts, ad-hoc connections, secret env patterns, file transfer status (
winrm_policy).Connect ad hoc or via saved hosts, with per-call overrides for host, credentials, auth method, SSL, port, timeouts, certificates, and tags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@winrm-mcp Run PowerShell command Get-Service on host sql01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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 |
| Default Windows host |
|
| Default user |
|
| Default 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-mcpSettings → 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-mcpOr 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.0then 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;envsets 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 toWINRM_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 |
| any | Comma-separated glob patterns ( |
|
|
|
|
|
|
|
| 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. |
| unset | Enables |
Multi-host inventory
Hosts can be stored in either inventory scope:
user(default):${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.jsonon Linux/macOS, or the matching%APPDATA%location on Windows.project:.winrm-mcp/inventory.jsonunder 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-mcpThe 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 hostLive 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 credsspAvailable Tools
15 toolswinrm_downloadADestructive
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_cmdADestructive
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_manyBDestructive
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_powershellADestructive
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_deleteCDestructiveIdempotent
Delete a saved WinRM host.
Inputs: name (required), scope. Returns: object
winrm_host_getBRead-only
Get one saved WinRM host with its password redacted.
Inputs: name (required), scope. Returns: object
winrm_host_listBRead-only
List saved WinRM hosts with passwords redacted; optionally only hosts carrying a tag.
Inputs: tag, scope. Returns: object
winrm_host_saveBIdempotent
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_updateBIdempotent
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_initBIdempotent
Create an empty project or user inventory without replacing existing data by default.
Inputs: scope, overwrite. Returns: object
winrm_inventory_statusBRead-only
Show the project or user inventory path, existence, and saved host count.
Inputs: scope. Returns: object
winrm_inventory_validateBRead-only
Validate an inventory file and every saved WinRM host.
Inputs: scope. Returns: object
winrm_policyARead-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_testBRead-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_uploadADestructive
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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Control your authorized Windows computers via OAuth: files, shell, apps, and task status.
Manage servers through SSH.
Your agents' cloud for individuals and teams. Search, execute, packages, jobs, and credentials.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables management of Windows servers from Linux through an MCP server with per-user installation. Provides tools to control Windows systems via API with secure credential management.-
- AlicenseBqualityBmaintenanceEnables AI agents to securely manage and execute commands on remote Windows servers via WinRM, including PowerShell execution, system information retrieval, and service management.613 PyPI6MIT
- FlicenseNot gradedqualityDmaintenanceEnables remote Windows server administration and troubleshooting via WinRM and SSH PowerShell protocols.8-
- AlicenseAqualityCmaintenanceEnables executing commands and transferring files over SSH on multiple hosts concurrently, with auto-discovery from SSH config and support for various authentication methods.36 npmMIT