ssh-winrm-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SSH_WINRM_MCP_HOST | No | Host/interface to bind when using HTTP transport, for example 127.0.0.1. | |
| SSH_WINRM_MCP_PORT | No | Port to bind when using HTTP transport, for example 8765. | |
| SSH_WINRM_MCP_CONFIG | No | Custom path to the persistent inventory JSON file. When unset, the inventory is stored at ${XDG_CONFIG_HOME:-~/.config}/ssh-winrm-mcp/inventory.json on Linux/macOS or %APPDATA%\ssh-winrm-mcp\inventory.json on Windows. | |
| SSH_WINRM_MCP_TRANSPORT | No | Transport to use. Defaults to stdio. Supports stdio, Streamable HTTP (streamable-http), and SSE transports. | |
| SSH_WINRM_MCP_LOCAL_ROOT | No | Root directory confining uploads, downloads and local scripts. Defaults to ${XDG_DATA_HOME:-~/.local/share}/ssh-winrm-mcp/files. Relative paths are relative to this root. Set to / to allow any path. The server's config directory is always refused. | |
| SSH_WINRM_MCP_ALLOW_ADHOC | No | Whether ad-hoc connection objects are allowed. Defaults to true. When false, only saved profiles may be used; per-call connection overrides may then only change timeouts. | |
| SSH_WINRM_MCP_COMMANDS_DIR | No | Custom directory for persistent external command-group modules. Defaults beside the inventory: ~/.config/ssh-winrm-mcp/commands/ on Linux/macOS or %APPDATA%\ssh-winrm-mcp\commands\ on Windows. | |
| SSH_WINRM_MCP_ALLOWED_HOSTS | No | Comma-separated glob patterns (for example *.lab.example,10.0.110.*) limiting which hosts may be connected to. Defaults to allowing any host. Connections to non-matching hosts are refused, including saved profiles. | |
| WINRM_DISABLE_SSL_CERT_CHECK | No | Set to 1 to disable WinRM SSL certificate validation as a process-wide default. An explicit cert_validation value in a profile or ad-hoc connection takes precedence. Use only for trusted hosts. | |
| SSH_WINRM_MCP_MAX_OUTPUT_CHARS | No | Maximum number of output characters to return from remote commands. | |
| SSH_WINRM_MCP_SECRET_ENV_PATTERNS | No | Comma-separated glob patterns limiting which environment variables password_env and other *_env fields may read. Defaults to *PASSWORD*,*PASSWD*,*_PASS,*PASSPHRASE*. | |
| SSH_WINRM_MCP_ALLOW_INSECURE_BASIC | No | Whether WinRM basic auth over plain HTTP is allowed. Defaults to false. When false, cleartext password authentication is refused. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Remote administration over SSH and WinRM. Use stored profiles or pass an ad-hoc connection object. Named sessions preserve remote shell/runspace state. Long commands can run as asynchronous jobs.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| remote_policyA | Show the server version and the operator's security policy: allowed hosts, whether ad-hoc connections are allowed, which environment variables *_env fields may read, and the local directory that file and script tools are confined to. |
| remote_inventory_statusA | Show the automatic local inventory path and whether it already exists. |
| remote_inventory_initC | Create an empty local inventory. A config path is not required to start the server. |
| remote_inventory_validateA | Validate the inventory JSON and every stored SSH/WinRM profile. |
| remote_profile_listA | List saved profiles with secrets redacted; optionally filter by protocol or tag. |
| remote_profile_getA | Read one saved connection profile with secrets redacted. |
| remote_profile_createC | Create a saved profile. Prefer password_env and passphrase environment references. |
| remote_profile_updateB | Update a profile by merging changes, or fully replace it with replace=true. Use remove_fields to delete optional settings. Required fields must remain valid. |
| remote_profile_renameC | Rename a saved profile. |
| remote_profile_deleteC | Delete a saved connection profile. |
| remote_testA | Test a saved or ad-hoc connection by executing a harmless marker command. For WinRM HTTPS on port 5986, keep ssl=true. If the server uses a self-signed certificate, also set cert_validation=false; ssl=false selects plain HTTP instead of disabling certificate verification. |
| remote_executeA | Execute one command using a short-lived SSH or WinRM connection. connection may override a profile or fully describe an ad-hoc target, for example: {"protocol":"ssh","host":"server","username":"root","password":"..."}. For self-signed WinRM HTTPS use ssl=true and cert_validation=false. WinRM shell may be powershell or cmd. SSH executes through the remote user's shell. |
| remote_run_programC | Run an executable with a safely quoted argument list on a saved or ad-hoc target. |
| remote_run_scriptB | Upload and run an inline or local script. Supports bash/sh, PowerShell, batch, Python, and executables. |
| remote_uploadC | Copy a local file or directory to a remote host. Set recursive=true for directories. |
| remote_downloadC | Copy a remote file or directory to the MCP server. Set recursive=true for directories. |
| remote_session_openA | Open a named persistent SSH shell or WinRM PowerShell runspace. Sessions remain alive until closed or until the MCP server process exits. SSH shell state such as cwd and exported variables persists. WinRM uses one reusable PSRP runspace. |
| remote_session_listA | List active named sessions and their health. |
| remote_session_executeB | Run a command inside a named persistent session and wait for completion. |
| remote_session_closeA | Close one named session and its remote shell/runspace. |
| remote_session_close_allB | Close every active session. |
| remote_session_cleanup_idleB | Close named sessions which have been idle for at least the requested number of seconds. |
| remote_job_startB | Start a long-running command in a named session and return immediately with a job ID. |
| remote_job_listB | List asynchronous jobs, optionally restricted to one session. |
| remote_job_statusB | Get the current state of a long-running job. |
| remote_job_resultB | Get a job result. Set wait=true to wait, optionally bounded by timeout seconds. |
| remote_job_cancelB | Interrupt and cancel a running job. SSH cancellation closes that named shell session. |
| remote_command_groupsA | List command groups and the persistent local plug-in directory. Set create_directory=true once to create the folder. Set reload=true after adding or editing a module. |
| remote_command_group_describeC | Describe the actions and parameters available in a specialized command group. |
| remote_command_group_runB | Build and run a specialized action, such as user management, services, reboot, or system inventory. Use either session_name or profile/connection. dry_run returns the generated command without executing it. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| profiles_resource | Saved profile names and redacted settings. |
| command_groups_resource | Available specialized command groups. |
TDQS
Scored across 30 tools
Most tools are cleanly separated by resource (profiles, sessions, jobs, inventory, files) and action. A few boundaries are fuzzy: remote_execute vs remote_session_execute vs remote_run_program vs remote_run_script all execute things, and the distinction relies on descriptions. But the one-shot vs persistent-session vs job split is coherent enough to guide selection.
All tools share the snake_case remote_ prefix and are readable, but verb ordering is mixed: resource-first (remote_job_start, remote_profile_create, remote_session_open) alongside action-first (remote_execute, remote_run_program, remote_run_script, remote_test). The inconsistency is tolerable but not a clean pattern.
Thirty tools is heavy for the scope and pushes well past the typical 3-15 sweet spot. Job, session, profile, and inventory lifecycles each add several tools, inflating the surface more than the core purpose requires.
Coverage is strong: full profile CRUD (list/get/create/update/delete/rename), session lifecycle, job lifecycle, file transfer, scripts, and inventory validation are all present. Minor gaps like bulk job cleanup or richer inventory editing exist but are workaroundable.