WinRM MCP Server

A Model Context Protocol (MCP) server that enables AI agents to execute PowerShell commands on remote Windows machines via WinRM.

Quick Start

1. Install uv if you haven't already (installation guide)
2. Add the following to your VS Code MCP configuration:

{
  "servers": {
    "winrm-mcp-server": {
      "command": "uvx",
      "args": ["winrm-mcp-server"],
      "env": {
        "WINRM_MCP_HOSTNAME": "your-windows-host.com",
        "WINRM_MCP_USERNAME": "your-username",
        "WINRM_MCP_PASSWORD": "your-password"
      }
    }
  }
}

1. That's it! No installation required - uvx handles everything automatically.

Features

• Remote Command Execution: Execute PowerShell commands on remote Windows hosts
• Secure Authentication: Uses username/password authentication with support for both HTTP and HTTPS
• Error Handling: Comprehensive error handling with semantic separation of error types
• Timeout Management: Configurable command timeouts (default: 5 minutes)
• Comprehensive Logging: Detailed logging compatible with VS Code's MCP Server output
• Connection Flexibility: Automatically tries HTTPS first, falls back to HTTP if needed

Installation

Using uvx (Recommended)

The recommended way to use this MCP server is with uvx, which runs the package without installing it globally:

# No installation needed! uvx will handle everything

Benefits of using uvx:

• ✅ No global package installation required
• ✅ Automatic dependency management and isolation
• ✅ Always uses the latest version from PyPI
• ✅ Cleaner system without package conflicts
• ✅ uvx handles Python environment setup automatically

Prerequisites: Make sure you have uv installed. If not, install it with:

# On Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

From PyPI (Alternative)

If you prefer to install the package globally:

pip install winrm-mcp-server

From Source (Development)

1. Clone this repository
2. Install dependencies using uv:

cd winrm-mcp-server
uv sync

Configuration

The server can be configured via VS Code's MCP configuration. Add the following to your VS Code settings or MCP configuration file:

Using uvx (Recommended Configuration)

{
  "servers": {
    "winrm-mcp-server": {
      "command": "uvx",
      "args": ["winrm-mcp-server"],
      "env": {
        "WINRM_MCP_HOSTNAME": "remote.host.com",
        "WINRM_MCP_USERNAME": "username",
        "WINRM_MCP_PASSWORD": "secret"
      }
    }
  }
}

Using the installed package

{
  "servers": {
    "winrm-mcp-server": {
      "command": "winrm-mcp-server",
      "env": {
        "WINRM_MCP_HOSTNAME": "remote.host.com",
        "WINRM_MCP_USERNAME": "username",
        "WINRM_MCP_PASSWORD": "secret"
      }
    }
  }
}

Using from source (Development)

{
  "servers": {
    "winrm-mcp-server": {
      "command": "python",
      "args": ["run_server.py"],
      "cwd": "/path/to/winrm-mcp-server",
      "env": {
        "WINRM_MCP_HOSTNAME": "remote.host.com",
        "WINRM_MCP_USERNAME": "username",
        "WINRM_MCP_PASSWORD": "secret"
      }
    }
  }
}

Environment Variables

You can customize the server behavior using environment variables:

Required Variables:

• WINRM_MCP_HOSTNAME: Target Windows hostname or IP address (required)
• WINRM_MCP_USERNAME: Username for authentication (required)
• WINRM_MCP_PASSWORD: Password for authentication (required)

Optional Variables:

• WINRM_MCP_COMMAND_TIMEOUT: Command execution timeout in seconds (default: 300)
• WINRM_MCP_CONNECTION_PORT: Connection port to use (default: 5985 for HTTP, 5986 for HTTPS)
• WINRM_MCP_CONNECTION_TIMEOUT: Connection timeout in seconds (default: 30)
• WINRM_MCP_USE_HTTPS: Prefer HTTPS over HTTP (default: true)
• WINRM_MCP_SKIP_SSL_VERIFICATION: Skip SSL certificate verification (default: false)
• WINRM_MCP_MAX_RETRIES: Maximum retries for transient failures (default: 3)

Usage

The server exposes a single tool: execute_command

Parameters

• command: PowerShell command to execute

Example

{
  "tool": "execute_command",
  "arguments": {
    "command": "Get-Process | Select-Object Name, CPU | Sort-Object CPU -Descending | Select-Object -First 10"
  }
}

Security Considerations

• Credentials are handled securely and not logged
• Supports both HTTP and HTTPS WinRM connections
• SSL certificate validation can be configured
• Command input is validated to prevent injection attacks

Requirements

Target Windows Machines

The target Windows machines must have WinRM enabled and configured:

# Enable WinRM
Enable-PSRemoting -Force

# Configure WinRM for HTTP (if needed)
winrm quickconfig

# Configure WinRM for HTTPS (recommended)
# (Requires SSL certificate configuration)

Network Requirements

• WinRM HTTP port (default: 5985) or HTTPS port (default: 5986) must be accessible
• Windows Firewall rules must allow WinRM traffic

Error Types

The server provides semantic error separation:

• ConnectionError: Network connectivity issues
• AuthenticationError: Invalid credentials or authentication failures
• CommandExecutionError: Command execution failures
• TimeoutError: Command execution timeouts

Development

Setting up the development environment

git clone https://github.com/antonvano-microsoft/winrm-mcp-server.git
cd winrm-mcp-server
uv sync --dev

Testing the package locally

You can test the package locally using uvx with the built distribution:

# Build the package first
uv build

# Test with uvx using the local wheel file
uvx --from ./dist/winrm_mcp_server-*.whl winrm-mcp-server

Running Tests

uv run pytest

Code Formatting

uv run black .
uv run isort .

Type Checking

uv run mypy .

Building and Publishing

To build the package:

uv build

To publish to PyPI (maintainers only):

uv publish

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate and follow the existing code style.

License

MIT License - see LICENSE file for details.