winrig MCP server
Commit Nov 16, 2026Allows an AI client to remotely diagnose, examine, and administer Windows hosts over WinRM/NTLM.
Also known as fgbm/winrig
- Stars
- 1
- Tools
- 49
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 16, 2026
- License
- MIT
What is winrig MCP?
winrig allows an AI client to remotely diagnose, examine, and administer Windows hosts over WinRM/NTLM. It exposes 49 tools, such as connect, disconnect, list_sessions.
Summary generated from the project's README
About winrig MCP server
System administrators and developers can remotely manage Windows hosts through an AI client using winrig. This Rust-based server connects to any Windows host joined to an Active Directory domain via WinRM or NTLM. It functions as either a local stdio process or an HTTP service, providing a lightweight footprint of approximately 11 MiB of resident memory.
Users interact with the server through tools that cover file system management, service control, registry editing, and system diagnostics. While many tools are read-only by default, administrators can enable modifying operations like running PowerShell commands, executing scripts, or writing files by configuring specific environment variables. Security is prioritized by storing credentials as authenticated ciphertext and requiring profile tokens for authentication, ensuring no clear-text passwords exist in configurations or logs. The server is compatible with clients such as Claude Code, Cursor, and Codex.
What you can do with it
- 1Diagnose Windows system issuesAsk the AI to investigate service failures or system crashes by examining event logs and process details.
Written from the project's README. Every use case is checked against a quote from it.
winrig MCP tools 49
Detected from the READMEconnectdisconnectlist_sessionslist_directoryfind_filesread_filesearch_file_contentfile_infocompare_filesget_event_loglist_event_logsget_services
Show all 49 toolsShow fewer tools
get_service_configlist_processesget_open_handlesget_printersget_print_jobsget_system_infoget_disk_spaceget_perf_snapshotget_registryget_certificatesget_network_configtest_networkget_environment_variablesget_scheduled_tasksget_local_usersget_user_groupsget_security_contextget_permissionsget_tcp_connectionsget_dns_cacheget_installed_softwareresolve_dns_nameget_ad_objectget_ad_membershipfind_ad_objectsget_ad_domain_infoget_ad_healthget_ad_stale_objectsset_service_start_typekill_processset_registryflush_dnswrite_filerun_commandrun_scriptdownload_fileupload_file
Configuration
WINRIG_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefgbm/winrig is public and reachablegithub.com/fgbm/winrig ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-26github.com/fgbm/winrig ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model49 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubwinrig
English | Русский
The full documentation is at https://fgbm.github.io/winrig/.
An MCP server for the remote administration of Windows hosts over WinRM/NTLM, written in Rust. Diagnose, examine and administer any Windows host that joined the AD domain. Use Cursor, Claude Code, Codex, opencode or any MCP (Model Context Protocol) client. Enter the AD password one time through winrig setup. The server keeps the password only as authenticated ciphertext under a key that stays at the client. The server never writes the password in clear text into the client configuration.
winrig is the Rust successor of the Python project win-mcp-server. It keeps the same domain rules, module boundaries and tool contracts. It ships as one static binary without a container or an interpreter. It runs either as an HTTP service (winrig serve) or as a local stdio process (winrig stdio).
- Low memory, one binary: one release binary, with no runtime and no container. Resident memory stays near 11 MiB after start and repeated requests on the development computer (
VmRSSfrom/proc). - 43 tools plus
write_file,run_command,run_script, the file operations,download_fileandupload_file, when the operator enables them. They cover the file system, services, registry, event logs, certificates, processes, network, scheduled tasks and more. The current version includes these ported tools. The Python versionwin-mcp-serverhad archive tools (compress and expand),invoke_http_requestand SFTP tools. The current version does not include those tools yet. - One process for each profile:
winrig setupcreates an encrypted profile. The printed profile token is the only key, andsetupshows it one time. A second process on the same profile refuses to start and points to the HTTP mode. - Two secrets, one for each request: a request authenticates with
WINRIG_AUTH_TOKEN(the header path withX-AD-User) or with a profile token. The profile token gives the identity and makes the server ignoreX-AD-*. - No secrets on disk: no account credentials in configurations or in logs. The profile file holds only authenticated ciphertext.
Why Rust
- One release binary,
cargo build --release; without Docker, without Python, without pip. - Memory stays bounded and small. One long command cannot block another request, because the transport is asynchronous.
- The WinRM/NTLM client, the MCP protocol and the HTTP stack are mature crates. The project therefore carries the domain logic, not the protocol plumbing. See
docs/adr/0007-rust-stack.md.
Tools
Session
| Tool | Description |
|---|---|
connect |
Open a WinRM session to a Windows host and return a session_id (HTTP 5985 or HTTPS 5986 through use_ssl) |
disconnect |
Close the active WinRM session |
list_sessions |
List the active WinRM sessions with usage details |
File system (read only)
| Tool | Description |
|---|---|
list_directory |
List the files and directories at a path |
find_files |
Find files recursively by a pattern |
read_file |
Read the content of a file with line numbers. The tail mode can drop the lines that contain a literal text |
search_file_content |
Search text in a file or a directory, like grep. The tool can return the last matches, count the matches, and filter the lines by the timestamp at the start |
file_info |
The metadata of a file or a directory in JSON |
compare_files |
A line-by-line diff of two files |
System diagnostic (read only)
| Tool | Description |
|---|---|
get_event_log |
The Windows event log: crashes, service failures, authentication errors |
list_event_logs |
The event log channels with the record count and the enabled state |
get_services |
A summary of the services, or the full details of each service in JSON |
get_service_config |
One service: the start type, the account, the binary path and the recovery actions. The start type is Automatic, AutomaticDelayed, Manual or Disabled. The recovery actions hold the action, the delay and the reset period |
list_processes |
The processes with a sort by CPU, memory or handles |
get_open_handles |
The processes that hold a file open, with the PID, the name and the start time. It uses the Restart Manager, so a host needs no Sysinternals handle.exe |
get_printers |
The printers with the share name, the driver, the port, the port host and number, the state as the PrinterStatus name and the job count |
get_print_jobs |
The print jobs of one printer with the job id, the state, the size and the submit time. The document name and the owner stay hidden unless include_personal_data is true |
get_system_info |
The OS version, uptime, RAM, CPU count, domain, time zone |
get_disk_space |
The free space on all fixed disks |
get_perf_snapshot |
A snapshot of CPU, memory, disk I/O and network, independent of the locale |
get_registry |
Read a registry key or value and, on request, the child key names (read only) |
get_certificates |
The certificates in the personal store, sorted by the days to expiry |
get_network_config |
IP, gateway and DNS for each network adapter |
test_network |
An ICMP ping or a TCP port check from the host |
Identity and configuration (read only)
| Tool | Description |
|---|---|
get_environment_variables |
The environment variables by scope |
get_scheduled_tasks |
The scheduled tasks with the last/next run and the result |
get_local_users |
The local accounts with the status and the last logon |
get_user_groups |
The membership in local groups |
get_security_context |
The identity of the current session, the groups, the privileges |
get_permissions |
The ACL entries for files and directories |
Network and software (read only)
| Tool | Description |
|---|---|
get_tcp_connections |
The active TCP connections, filtered by state, port, PID or process name, with an optional grouped summary |
get_dns_cache |
The local DNS client cache |
get_installed_software |
The installed software from the 64-bit and 32-bit uninstall keys |
resolve_dns_name |
The DNS resolution chain from the host |
Active Directory — decided, but not built
The binary has none of these tools today. The section records a decision (ADR-0014, slices W19–W21), not a capability. It is here because the absence itself is misleading. An agent that sees WinRM and a host in the domain assumes that the directory is available, but it is not.
Why: NTLM gives the host a network logon without delegatable credentials. A directory request from a host that is a domain member is therefore a second hop to the domain controller, and it fails with An operations error occurred. run_command will not change this. It runs in the same session with the same token. The route that works needs no delegation at all: connect to the domain controller itself, where the request is local. Today AD touches only get_security_context, and only because the domain groups are in the session token.
The project plans these tools in slice W19. They are read only and use System.DirectoryServices, not RSAT cmdlets. Those cmdlets go to ADWS and need an installed module and a running service:
| Tool | Description |
|---|---|
get_ad_object |
One user, group or computer: the account state, the password dates, the last logon, the DN, the OU |
get_ad_membership |
The membership in both directions, nested when necessary |
find_ad_objects |
A search by name or sAMAccountName with a result cap |
get_ad_domain_info |
The domain, the forest, the functional levels, the FSMO roles, the controllers, the trusts, the sites, the password policy and the PSO |
get_ad_health |
The replication partners and the lag, the NTDS/DNS/ADWS/W32Time services, the SYSVOL state |
get_ad_stale_objects |
The stale users and computers by lastLogonTimestamp and pwdLastSet |
The same ADR decides the directory write (slices W20–W21), and it stays intentionally outside the first wave. It will be off by default behind WINRIG_ALLOW_AD_WRITE. It will confirm each call with the object DN. It will reject protected objects and built-in groups before any network activity. It will accept exactly one explicitly named object for each call, and never a filter. It will accept an attribute only if the attribute passes WINRIG_AD_WRITABLE_ATTRIBUTES. The current binary does not read any of these variables. The project does not plan a change of the domain or the forest topology: FSMO role seizure, metadata cleanup or forced replication. The project does not plan the deletion of directory objects either.
Modifying operations (all need confirmation)
| Tool | Description |
|---|---|
restart_service / stop_service / start_service |
Manage the services with the state before and after. stop_service verifies the stop: it waits wait_seconds (15 by default), reads the state and the System events 7031/7034/7036, and reports an error when the service runs again. With disable=true it sets the start type to Disabled before the stop |
set_service_start_type |
Set the start type (Automatic, AutomaticDelayed, Manual or Disabled). The confirmation shows the current and the new start type. The tool refuses a service that is critical for the remote session |
kill_process |
Terminate a process by PID. The confirmation shows the name, the executable path (with no arguments) and the start time. The command line is never read, so a secret in it cannot leak (DR-4) |
set_registry |
Write a registry value. The old value and the new value appear only as hidden; the prompt shows whether the old value is present and its type |
delete_file / delete_directory |
Delete with a confirmation prompt; the tool rejects protected paths, including by the actual location of the system on the host. delete_file accepts the operator allowlist WINRIG_WRITE_ALLOW_PATHS; the recursive delete_directory does not (DR-6) |
flush_dns |
Clear the DNS client cache |
write_file |
Write a file with a full replacement. Off by default: set WINRIG_ALLOW_FILE_WRITE=true, or the server does not declare the tool and no call can reach it |
run_command |
Run an arbitrary PowerShell command. Off by default: set WINRIG_ALLOW_COMMAND_EXEC=true, or the server does not declare the tool and no call can reach it. The confirmation shows the full command text. The server refuses a command outside a non-empty WINRIG_ALLOWED_COMMANDS before any network activity |
run_script |
Run a PowerShell script that is longer than one WinRS command line. Off by default: set WINRIG_ALLOW_SCRIPT_EXEC=true, or the server does not declare the tool and no call can reach it. The server writes the script into a temporary .ps1 in the session temp directory. It reads the file and runs its text as a script block, then tries to delete the file. The script has no $PSScriptRoot, no $PSCommandPath and no arguments. One confirmation covers the whole operation and shows the whole script and its SHA-256. The prefix list WINRIG_ALLOWED_COMMANDS does not filter a script |
copy_file / move_file / rename_file / create_directory |
Copy, move or rename a file or a directory, and create a directory with its parents. Off by default: set WINRIG_ALLOW_FILE_OPS=true, or the server does not declare the tools and no call can reach them. All four prompt for confirmation. A directory copy shows the counts, and it refuses a source tree that holds a symbolic link or a junction. A move on one volume renames; across volumes it copies a file and deletes the source, and it refuses a cross-volume directory move (DR-6). A rename takes one new name. None of the four replaces an existing directory, and an existing target needs overwrite (except create_directory, which refuses it). The target obeys WINRIG_WRITE_ALLOW_PATHS; a copy source may lie under a system directory, because a copy only reads it |
download_file |
Copy a file from the host into the local transfer directory. Off by default: set WINRIG_ALLOW_FILE_DOWNLOAD=true, or the server does not declare the tool and no call can reach it. The tool reads the file on the host in chunks and writes it into WINRIG_TRANSFER_DIR, and it compares the SHA-256 of the two sides. The reply carries the name, the size and the hash, not the content. Every download needs a confirmation (ADR-0017 §21–28) |
upload_file |
Copy a file from the local transfer directory to the host. Off by default: set WINRIG_ALLOW_FILE_UPLOAD=true, or the server does not declare the tool and no call can reach it. The tool hashes the local file and shows the SHA-256 in the confirmation. It sends the bytes in windows of 4 MiB into a temporary file. Each window goes through the standard input of a host command. The host hashes that file before the rename. The target obeys WINRIG_WRITE_ALLOW_PATHS, and an existing target needs overwrite. Every upload needs a confirmation (ADR-0017 §26) |
Each confirmation names the host of the session, the user of the request and the tool. It names the target and the operation with the details that are available before the call. It holds one plain line that states the effect. The line states whether the operator can undo it. A hidden value appears only as hidden: the old and new values of set_registry and the content of write_file are hidden values. The text of a command and the text of a script appear in full, without the 200-character cap, because the operator confirms what will run. kill_process does not read the command line at all. The server sanitizes each field and caps the other fields at 200 characters. A cut path keeps its tail, and a cut field carries the marker ... inside the cap. The text is English and does not depend on the language of the host. The file operations show the resolved source and target, the size or the counts, and the overwrite state.
write_file rejects protected paths with the same list that guards deletion. It rejects an existing file if overwrite is not set. Before confirmation, the host reports where the file will really land and where the system directories are (SystemRoot, ProgramFiles, ProgramFiles(x86), ProgramData, user profiles). Therefore Windows on a volume other than C: is equally protected. The tool rejects a path with an 8.3 name (PROGRA~1), because only the host can compare it with the list. The tool checks the administrative share \\host\C$\... as C:\.... The server protects the shares ADMIN$, PRINT$, SYSVOL and NETLOGON in full. The tool does not resolve junctions and symlinks in the parent directories of the target (ADR-0015). The operator can permit a write under a protected root with WINRIG_WRITE_ALLOW_PATHS (ADR-0017). Such an entry lifts the refusal for write_file and delete_file. The confirmation then carries a warning line that names the class. The allowlist never lifts the 8.3 refusal. It also never lifts the refusal of a symbolic link or a junction, because the operation would act on the link target. A device volume path (\\?\Volume{...}, \\?\GLOBALROOT) and an existing directory target are refused too. The audit records the entry that permitted a protected path. The content travels in chunks of about 1.5 KB, because the WinRS command line accepts about 8191 characters at most. The tool refuses a path so long that its commands would not fit this line. The limit is about 530 characters for UTF-8 and about 470 characters for the other encodings, for a path with no quote character. The tool is therefore good for configuration files and scripts, not for large volumes. WINRIG_MAX_WRITE_BYTES limits the size (64 KiB by default). The chunks land in a temporary file next to the target. A rename replaces the target. A failure in the middle therefore leaves the existing file untouched.
This length limit applies to the command line, not to the output. Write a script that does not fit in one command with write_file, then run the script by its path. The command stays short, however long the script is.
run_command is off by default. Set WINRIG_ALLOW_COMMAND_EXEC=true to declare it. It runs one PowerShell command. The operator confirms it, and the prompt shows the full command text. The server encodes the command text as a base64 UTF-16 string. It decodes the string into a script block on the host. A quote or a terminator in the text therefore cannot break out of the generated wrapper. The command must fit one WinRS command line, so the text holds at most 979 characters. A longer script goes through write_file and then runs by path, or through run_script. The server refuses a command outside a non-empty WINRIG_ALLOWED_COMMANDS before any network activity. The list is a set of prefixes, matched without case after a trim. An empty list admits any command. The list is not a boundary. A leading &, . or powershell -c starts with text the list need not contain. An alias, a call operator and an encoded command do the same. Any text after an allowed prefix runs. So ;, a newline, | and $(...) do not return control to the list. An entry of & or . alone admits every command. A script written with write_file and then started also goes around it (ADR-0013 §18). The list protects against an accidental command, not against intent. With run_command on and an empty list, the path protection of the other tools stops being a guarantee of the product. The same holds for the confirmation of the other modifying operations. They stay properties of their own tools. This is a deliberate choice of the operator (ADR-0013, Q-14).
run_script is off by default. Set WINRIG_ALLOW_SCRIPT_EXEC=true to declare it. It runs a PowerShell script that is longer than one WinRS command line. The server writes the script into a temporary .ps1 in the session temp directory in chunks. It reads the file and runs its text as a script block, then tries to delete the file. The script has no $PSScriptRoot, no $PSCommandPath and no arguments. The tool shows the SHA-256 of the script in the confirmation and records it in the audit, and it verifies the hash before the run. One confirmation covers the whole operation and shows the whole script, line by line and without the 200-character cap. The prefix list WINRIG_ALLOWED_COMMANDS does not filter a script, because the server cannot prefix-check the text of a script in a meaningful way. The confirmation states this. The script obeys WINRIG_MAX_WRITE_BYTES, and the output obeys the same limits as run_command. The result carries temp_file with the cleanup outcome, and a warning when the temporary file may remain. The tool can fail if the script produces no output for 60 seconds (ADR-0017 §29–34).
The file operations copy_file, move_file, rename_file and create_directory are off by default. Set WINRIG_ALLOW_FILE_OPS=true to declare them. copy_file copies a file or a directory. A directory copy is recursive, and the confirmation shows the file, directory and byte counts. The copy walks the source tree once and refuses it when it holds a symbolic link or a junction. The command repeats the check at run time. move_file renames the object on one volume. Across volumes it copies a file, verifies the size and then deletes the source. It refuses a cross-volume move of a directory, because the implied recursive delete falls under DR-6. Copy the directory and delete the source with two calls. rename_file changes the last component in the same directory, and it takes one new name. A separator, a reserved device name (CON, NUL, COM1, ...) and a trailing dot or space are refused. create_directory creates the final directory and each missing parent. The confirmation shows the number of created levels and the shallowest created level, which also passes the write boundary. The target of each tool obeys the allowlist WINRIG_WRITE_ALLOW_PATHS. The source of a copy is read-only, so it may lie under a system directory. None of the four replaces an existing directory, and an existing target needs overwrite (except create_directory, which refuses it). The tools reach the host with the [IO.File] and [IO.Directory] classes, so a wildcard in a path cannot expand. A partial copy or move is an error, never a success. A long copy or move can fail if it produces no output for 60 seconds. A read-only target or source fails the operation with a clear error, because the tool has no -Force and never clears the read-only attribute. An overwrite keeps the replaced file's access control list and attributes. write_file also uses the host-resolved .NET path for its chunks.
download_file is off by default. Set WINRIG_ALLOW_FILE_DOWNLOAD=true to declare it. It reads a file on the host and writes it into the local transfer directory. First the tool reads the size and the modification time of the source. It refuses a file above WINRIG_MAX_TRANSFER_BYTES (256 MiB by default) before any read. The confirmation shows the resolved remote path, the size, the modification time and the local destination. It shows no hash, because the hash is not known before the read. The tool then reads the file in windows of 16 MiB through a raw channel, as base64 lines of 1 MiB. The output is continuous, so a large file does not time out, and the whole file never loads into the host memory. The host reads with a shared read and delete, so a file that another process holds open (a live log) still copies. The tool hashes the bytes while it reads them. After the last window, one more host pass hashes exactly the scanned length and compares the two digests. A mismatch or a short file is a refusal with the text "the source changed during the transfer". The tool writes the windows into a temporary file next to the target. A failure or a cancel removes that file, so no partial file remains. The reply carries the name, the size and the hash. The content never goes inline into the result. The local endpoint is WINRIG_TRANSFER_DIR, the transfer subdirectory of the state directory by default. In HTTP mode the server isolates each user in a subdirectory of its canonical identity (DR-3). The directory and its files use the private modes (0700/0600). The tool takes one plain local file name. It refuses a separator, a .. component, a leading dot, a reserved device name, a symbolic link and a control or format character. An existing local file needs overwrite. A source that is a directory, a symbolic link or a junction is refused. A source under a system directory is allowed, and the confirmation warns for it. Every download needs a confirmation, because it moves data off the host. The audit records the resolved paths, the size, both hashes and the confirmation state. It never records the content (ADR-0017 §21–28).
upload_file is off by default. Set WINRIG_ALLOW_FILE_UPLOAD=true to declare it. It copies a file from the local transfer directory to the host. The tool takes one plain local file name and the absolute remote path. It reads only from the directory of the request user (DR-3). It refuses a symbolic link, an item that is not a regular file and a file that another user can write. On Unix it also refuses a file with more than one har
winrig MCP questions
What tools does winrig MCP provide?
It exposes 49 tools, including connect, disconnect, list_sessions, list_directory, find_files.
How does winrig handle security for passwords?
The server keeps the password only as authenticated ciphertext under a key that stays at the client, and never writes it in clear text into the client configuration.
Does the server require a container or a specific runtime?
No, it is a single static Rust binary that runs without a container or an interpreter.