Architecture

System design, source layout, and execution model for mcp-windows.

Overview

Claude Code  <-->  MCP (stdio)  <-->  mcp_windows  <-->  PowerShell/Win32
                                        |
                                        ├── shell.ts (executor + sessions)
                                        └── tools/*.ts (22 tool modules)

mcp-windows bridges AI assistants with the Windows desktop via the Model Context Protocol. Each tool module registers its tools with the MCP server at startup. Tools execute PowerShell commands or use inline C# for Win32 API access.

Source Map

File	Purpose
`src/index.ts`	Server entry point, imports and registers all tool modules
`src/shell.ts`	PowerShell/cmd/bash executor, persistent terminal session manager
`src/tools/execute.ts`	`windows_execute` -- generic shell command execution
`src/tools/process.ts`	`windows_process_list`
`src/tools/process_kill.ts`	`windows_process_kill`
`src/tools/audio.ts`	`windows_audio_get`, `windows_audio_set` -- COM audio via inline C#
`src/tools/audio_apps.ts`	`windows_audio_app_volumes`
`src/tools/system.ts`	`windows_system_info` -- WMI/CIM queries
`src/tools/terminal.ts`	`windows_terminal_start/send/read/list/kill` -- persistent sessions
`src/tools/filesystem.ts`	`windows_file_read/write/edit`, `windows_search`
`src/tools/service.ts`	`windows_service_list`, `windows_service_control`
`src/tools/power.ts`	`windows_power_get`, `windows_power_action`
`src/tools/network.ts`	`windows_network_info`
`src/tools/netstat.ts`	`windows_network_connections`
`src/tools/drives.ts`	`windows_drives`, `windows_file_search`
`src/tools/display.ts`	`windows_display_get/set`, `windows_screenshot` -- P/Invoke
`src/tools/window.ts`	`windows_window_list`, `windows_window_control` -- P/Invoke
`src/tools/clipboard.ts`	`windows_clipboard_get/set` -- STA subprocess
`src/tools/notification.ts`	`windows_notification_send`
`src/tools/scheduler.ts`	`windows_task_scheduler_list/manage`
`src/tools/registry.ts`	`windows_registry_read/write`
`src/tools/environment.ts`	`windows_env_get/set`
`src/tools/startup.ts`	`windows_startup_list/manage`
`src/tools/config.ts`	`windows_mcp_config`
`src/tools/apps.ts`	`windows_installed_apps`
`src/tools/dialog.ts`	`windows_dialog`
`src/tools/recycle_bin.ts`	`windows_recycle_bin`

Execution Model

One-shot Commands

Most tools use runPowerShell() from shell.ts:

Tool receives parameters from MCP
Builds a PowerShell script string
Spawns powershell.exe -NoProfile -NonInteractive -Command <script>
Captures stdout/stderr, parses JSON where applicable
Returns formatted text to the MCP client

Persistent Sessions

Terminal tools (windows_terminal_*) use spawn() with piped stdio:

startSession() spawns a shell process (pwsh, cmd, python, etc.)
stdout/stderr are collected into a ring buffer (5000 lines max)
sendToSession() writes to stdin
readSessionOutput() returns lines with offset/length pagination
Sessions are tracked by PID in an in-memory Map

Win32 API Access

Tools needing native Windows APIs (audio, windows, display) use inline C# via PowerShell Add-Type:

PowerShell → Add-Type (C# with P/Invoke) → user32.dll / ole32.dll / Core Audio COM

COM Threading

Windows COM objects (audio, clipboard) require STA (Single-Threaded Apartment) threads. Node.js runs in MTA, so these tools spawn a separate powershell.exe -STA subprocess.

Design Decisions

Decision	Rationale
PowerShell as execution engine	Available on all Windows, rich WMI/CIM/cmdlet ecosystem
Inline C# via Add-Type	Avoids shipping compiled binaries, leverages .NET Framework on Windows
STA subprocess for COM	Solves COM threading without native Node.js addons
Ring buffer for sessions	Prevents unbounded memory growth from chatty processes
No config file required	Local system MCP -- no API keys or connections needed
HKLM write gate	Safety measure -- system-wide registry changes need explicit override

API -- Complete tool reference
Installation -- Build and setup

Repo: mcp-windows · MokoStandards

Field	Value
Minimum Version	05.00.00
Platform	mcp-server
Applies To	mcp-windows

Revision	Date	Author	Description
1.0	2026-05-25	Moko Consulting	Initial version