| Name | winrm-mcp-server JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A Model Context Protocol (MCP) server for executing PowerShell commands on remote Windows machines via WinRM |
| upload_time | 2025-08-11 09:25:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
automation
mcp
powershell
remote
windows
winrm
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# WinRM MCP Server
A Model Context Protocol (MCP) server that enables AI agents to execute PowerShell commands on remote Windows machines via WinRM.
[](https://badge.fury.io/py/winrm-mcp-server)
[](https://pypi.org/project/winrm-mcp-server/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/antonvano-microsoft/winrm-mcp-server/actions)
## Quick Start
1. Install `uv` if you haven't already ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
1. Add the following to your VS Code MCP configuration:
```json
{
"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:
```bash
# 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:
```bash
# 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:
```bash
pip install winrm-mcp-server
```
### From Source (Development)
1. Clone this repository
2. Install dependencies using `uv`:
```bash
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)
```json
{
"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
```json
{
"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)
```json
{
"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
```json
{
"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:
```powershell
# 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
```bash
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:
```bash
# 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
```bash
uv run pytest
```
### Code Formatting
```bash
uv run black .
uv run isort .
```
### Type Checking
```bash
uv run mypy .
```
### Building and Publishing
To build the package:
```bash
uv build
```
To publish to PyPI (maintainers only):
```bash
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "winrm-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "automation, mcp, powershell, remote, windows, winrm",
"author": null,
"author_email": "Anton Vanco <vanco.anton@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/70/ba/d6c0fbb8c012fd0f4304ce98f7a49a792ffabc572309fc881637261fcf47/winrm_mcp_server-0.1.3.tar.gz",
"platform": null,
"description": "# WinRM MCP Server\n\nA Model Context Protocol (MCP) server that enables AI agents to execute PowerShell commands on remote Windows machines via WinRM.\n\n[](https://badge.fury.io/py/winrm-mcp-server)\n[](https://pypi.org/project/winrm-mcp-server/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/antonvano-microsoft/winrm-mcp-server/actions)\n\n## Quick Start\n\n1. Install `uv` if you haven't already ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))\n1. Add the following to your VS Code MCP configuration:\n\n```json\n{\n \"servers\": {\n \"winrm-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"winrm-mcp-server\"],\n \"env\": {\n \"WINRM_MCP_HOSTNAME\": \"your-windows-host.com\",\n \"WINRM_MCP_USERNAME\": \"your-username\",\n \"WINRM_MCP_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n\n1. That's it! No installation required - `uvx` handles everything automatically.\n\n## Features\n\n- **Remote Command Execution**: Execute PowerShell commands on remote Windows hosts\n- **Secure Authentication**: Uses username/password authentication with support for both HTTP and HTTPS\n- **Error Handling**: Comprehensive error handling with semantic separation of error types\n- **Timeout Management**: Configurable command timeouts (default: 5 minutes)\n- **Comprehensive Logging**: Detailed logging compatible with VS Code's MCP Server output\n- **Connection Flexibility**: Automatically tries HTTPS first, falls back to HTTP if needed\n\n## Installation\n\n### Using uvx (Recommended)\n\nThe recommended way to use this MCP server is with `uvx`, which runs the package without installing it globally:\n\n```bash\n# No installation needed! uvx will handle everything\n```\n\n**Benefits of using uvx:**\n\n- \u2705 No global package installation required\n- \u2705 Automatic dependency management and isolation\n- \u2705 Always uses the latest version from PyPI\n- \u2705 Cleaner system without package conflicts\n- \u2705 uvx handles Python environment setup automatically\n\n**Prerequisites:** Make sure you have `uv` installed. If not, install it with:\n\n```bash\n# On Windows (PowerShell)\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# On macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### From PyPI (Alternative)\n\nIf you prefer to install the package globally:\n\n```bash\npip install winrm-mcp-server\n```\n\n### From Source (Development)\n\n1. Clone this repository\n2. Install dependencies using `uv`:\n\n```bash\ncd winrm-mcp-server\nuv sync\n```\n\n## Configuration\n\nThe server can be configured via VS Code's MCP configuration. Add the following to your VS Code settings or MCP configuration file:\n\n### Using uvx (Recommended Configuration)\n\n```json\n{\n \"servers\": {\n \"winrm-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"winrm-mcp-server\"],\n \"env\": {\n \"WINRM_MCP_HOSTNAME\": \"remote.host.com\",\n \"WINRM_MCP_USERNAME\": \"username\",\n \"WINRM_MCP_PASSWORD\": \"secret\"\n }\n }\n }\n}\n```\n\n### Using the installed package\n\n```json\n{\n \"servers\": {\n \"winrm-mcp-server\": {\n \"command\": \"winrm-mcp-server\",\n \"env\": {\n \"WINRM_MCP_HOSTNAME\": \"remote.host.com\",\n \"WINRM_MCP_USERNAME\": \"username\",\n \"WINRM_MCP_PASSWORD\": \"secret\"\n }\n }\n }\n}\n```\n\n### Using from source (Development)\n\n```json\n{\n \"servers\": {\n \"winrm-mcp-server\": {\n \"command\": \"python\",\n \"args\": [\"run_server.py\"],\n \"cwd\": \"/path/to/winrm-mcp-server\",\n \"env\": {\n \"WINRM_MCP_HOSTNAME\": \"remote.host.com\",\n \"WINRM_MCP_USERNAME\": \"username\",\n \"WINRM_MCP_PASSWORD\": \"secret\"\n }\n }\n }\n}\n```\n\n### Environment Variables\n\nYou can customize the server behavior using environment variables:\n\n**Required Variables:**\n\n- `WINRM_MCP_HOSTNAME`: Target Windows hostname or IP address (required)\n- `WINRM_MCP_USERNAME`: Username for authentication (required)\n- `WINRM_MCP_PASSWORD`: Password for authentication (required)\n\n**Optional Variables:**\n\n- `WINRM_MCP_COMMAND_TIMEOUT`: Command execution timeout in seconds (default: 300)\n- `WINRM_MCP_CONNECTION_PORT`: Connection port to use (default: 5985 for HTTP, 5986 for HTTPS)\n- `WINRM_MCP_CONNECTION_TIMEOUT`: Connection timeout in seconds (default: 30)\n- `WINRM_MCP_USE_HTTPS`: Prefer HTTPS over HTTP (default: true)\n- `WINRM_MCP_SKIP_SSL_VERIFICATION`: Skip SSL certificate verification (default: false)\n- `WINRM_MCP_MAX_RETRIES`: Maximum retries for transient failures (default: 3)\n\n## Usage\n\nThe server exposes a single tool: `execute_command`\n\n### Parameters\n\n- `command`: PowerShell command to execute\n\n### Example\n\n```json\n{\n \"tool\": \"execute_command\",\n \"arguments\": {\n \"command\": \"Get-Process | Select-Object Name, CPU | Sort-Object CPU -Descending | Select-Object -First 10\"\n }\n}\n```\n\n## Security Considerations\n\n- Credentials are handled securely and not logged\n- Supports both HTTP and HTTPS WinRM connections\n- SSL certificate validation can be configured\n- Command input is validated to prevent injection attacks\n\n## Requirements\n\n### Target Windows Machines\n\nThe target Windows machines must have WinRM enabled and configured:\n\n```powershell\n# Enable WinRM\nEnable-PSRemoting -Force\n\n# Configure WinRM for HTTP (if needed)\nwinrm quickconfig\n\n# Configure WinRM for HTTPS (recommended)\n# (Requires SSL certificate configuration)\n```\n\n### Network Requirements\n\n- WinRM HTTP port (default: 5985) or HTTPS port (default: 5986) must be accessible\n- Windows Firewall rules must allow WinRM traffic\n\n## Error Types\n\nThe server provides semantic error separation:\n\n- **ConnectionError**: Network connectivity issues\n- **AuthenticationError**: Invalid credentials or authentication failures\n- **CommandExecutionError**: Command execution failures\n- **TimeoutError**: Command execution timeouts\n\n## Development\n\n### Setting up the development environment\n\n```bash\ngit clone https://github.com/antonvano-microsoft/winrm-mcp-server.git\ncd winrm-mcp-server\nuv sync --dev\n```\n\n### Testing the package locally\n\nYou can test the package locally using uvx with the built distribution:\n\n```bash\n# Build the package first\nuv build\n\n# Test with uvx using the local wheel file\nuvx --from ./dist/winrm_mcp_server-*.whl winrm-mcp-server\n```\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Formatting\n\n```bash\nuv run black .\nuv run isort .\n```\n\n### Type Checking\n\n```bash\nuv run mypy .\n```\n\n### Building and Publishing\n\nTo build the package:\n\n```bash\nuv build\n```\n\nTo publish to PyPI (maintainers only):\n\n```bash\nuv publish\n```\n\n## Contributing\n\nContributions 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.\n\nPlease make sure to update tests as appropriate and follow the existing code style.\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Model Context Protocol (MCP) server for executing PowerShell commands on remote Windows machines via WinRM",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/antonvano_microsoft/winrm-mcp-server/issues",
"Documentation": "https://github.com/antonvano_microsoft/winrm-mcp-server#readme",
"Homepage": "https://github.com/antonvano_microsoft/winrm-mcp-server",
"Repository": "https://github.com/antonvano_microsoft/winrm-mcp-server"
},
"split_keywords": [
"automation",
" mcp",
" powershell",
" remote",
" windows",
" winrm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "396aadbd527cf03ae8c87f374409c2bbd11b5576f4ffa020356f2daad78e68ec",
"md5": "4b6d6348f23107970f36c76d6fde6428",
"sha256": "fb8574ebfabb4a10cbbc6a79bcf993e4f9491987dd1a106b7a98919e5e1d995a"
},
"downloads": -1,
"filename": "winrm_mcp_server-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4b6d6348f23107970f36c76d6fde6428",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11087,
"upload_time": "2025-08-11T09:25:50",
"upload_time_iso_8601": "2025-08-11T09:25:50.540996Z",
"url": "https://files.pythonhosted.org/packages/39/6a/adbd527cf03ae8c87f374409c2bbd11b5576f4ffa020356f2daad78e68ec/winrm_mcp_server-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70bad6c0fbb8c012fd0f4304ce98f7a49a792ffabc572309fc881637261fcf47",
"md5": "c1e15412367454aa0f4785402b9648b6",
"sha256": "b7175405174ae46069601e9c093c2b8e1074eef15cfd4d23d1418abf8af3fdab"
},
"downloads": -1,
"filename": "winrm_mcp_server-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "c1e15412367454aa0f4785402b9648b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 73644,
"upload_time": "2025-08-11T09:25:51",
"upload_time_iso_8601": "2025-08-11T09:25:51.920592Z",
"url": "https://files.pythonhosted.org/packages/70/ba/d6c0fbb8c012fd0f4304ce98f7a49a792ffabc572309fc881637261fcf47/winrm_mcp_server-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 09:25:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "antonvano_microsoft",
"github_project": "winrm-mcp-server",
"github_not_found": true,
"lcname": "winrm-mcp-server"
}
