WinCtl MCP Server

Name: WinCtl MCP Server
Author: io.github.sitharaj88

io.github.sitharaj88/winctl

Repository Registry

What is the WinCtl MCP server?

Windows desktop control for AI agents: screen, UI Automation, input, processes, files, shell.

How to install WinCtl

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

WINCTL_PROFILE
Permission profile: readonly (observation only), standard (adds desktop interaction and file access), or full (adds process control and shell execution). Defaults to standard.
WINCTL_TIERS
Comma-separated capability tiers, overriding the profile. Any of: observe, interact, filesystem, manage, shell.
WINCTL_ALLOWED_PATHS
Semicolon-separated folders that file tools may access. Empty means the whole filesystem except protected Windows system directories.
WINCTL_CONFIRM_DESTRUCTIVE
Set to false to skip user confirmation prompts for destructive actions. Defaults to true.
WINCTL_AUDIT_LOG
Path to the JSONL audit log. Defaults to %LOCALAPPDATA%\winctl\audit.jsonl.
WINCTL_MAX_IMAGE_WIDTH
Screenshots are downscaled to at most this width in pixels. Defaults to 1600.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "winctl": {
      "command": "npx",
      "args": [
        "-y",
        "@sitharaj88/winctl"
      ],
      "env": {
        "WINCTL_PROFILE": "<YOUR_WINCTL_PROFILE>",
        "WINCTL_TIERS": "<YOUR_WINCTL_TIERS>",
        "WINCTL_ALLOWED_PATHS": "<YOUR_WINCTL_ALLOWED_PATHS>",
        "WINCTL_CONFIRM_DESTRUCTIVE": "<YOUR_WINCTL_CONFIRM_DESTRUCTIVE>",
        "WINCTL_AUDIT_LOG": "<YOUR_WINCTL_AUDIT_LOG>",
        "WINCTL_MAX_IMAGE_WIDTH": "<YOUR_WINCTL_MAX_IMAGE_WIDTH>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "winctl": {
      "command": "npx",
      "args": [
        "-y",
        "@sitharaj88/winctl"
      ],
      "env": {
        "WINCTL_PROFILE": "<YOUR_WINCTL_PROFILE>",
        "WINCTL_TIERS": "<YOUR_WINCTL_TIERS>",
        "WINCTL_ALLOWED_PATHS": "<YOUR_WINCTL_ALLOWED_PATHS>",
        "WINCTL_CONFIRM_DESTRUCTIVE": "<YOUR_WINCTL_CONFIRM_DESTRUCTIVE>",
        "WINCTL_AUDIT_LOG": "<YOUR_WINCTL_AUDIT_LOG>",
        "WINCTL_MAX_IMAGE_WIDTH": "<YOUR_WINCTL_MAX_IMAGE_WIDTH>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "winctl": {
      "command": "npx",
      "args": [
        "-y",
        "@sitharaj88/winctl"
      ],
      "env": {
        "WINCTL_PROFILE": "<YOUR_WINCTL_PROFILE>",
        "WINCTL_TIERS": "<YOUR_WINCTL_TIERS>",
        "WINCTL_ALLOWED_PATHS": "<YOUR_WINCTL_ALLOWED_PATHS>",
        "WINCTL_CONFIRM_DESTRUCTIVE": "<YOUR_WINCTL_CONFIRM_DESTRUCTIVE>",
        "WINCTL_AUDIT_LOG": "<YOUR_WINCTL_AUDIT_LOG>",
        "WINCTL_MAX_IMAGE_WIDTH": "<YOUR_WINCTL_MAX_IMAGE_WIDTH>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "winctl": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sitharaj88/winctl"
      ],
      "env": {
        "WINCTL_PROFILE": "<YOUR_WINCTL_PROFILE>",
        "WINCTL_TIERS": "<YOUR_WINCTL_TIERS>",
        "WINCTL_ALLOWED_PATHS": "<YOUR_WINCTL_ALLOWED_PATHS>",
        "WINCTL_CONFIRM_DESTRUCTIVE": "<YOUR_WINCTL_CONFIRM_DESTRUCTIVE>",
        "WINCTL_AUDIT_LOG": "<YOUR_WINCTL_AUDIT_LOG>",
        "WINCTL_MAX_IMAGE_WIDTH": "<YOUR_WINCTL_MAX_IMAGE_WIDTH>"
      }
    }
  }
}

Claude Code

claude mcp add winctl --env WINCTL_PROFILE=<YOUR_WINCTL_PROFILE> --env WINCTL_TIERS=<YOUR_WINCTL_TIERS> --env WINCTL_ALLOWED_PATHS=<YOUR_WINCTL_ALLOWED_PATHS> --env WINCTL_CONFIRM_DESTRUCTIVE=<YOUR_WINCTL_CONFIRM_DESTRUCTIVE> --env WINCTL_AUDIT_LOG=<YOUR_WINCTL_AUDIT_LOG> --env WINCTL_MAX_IMAGE_WIDTH=<YOUR_WINCTL_MAX_IMAGE_WIDTH> -- npx -y @sitharaj88/winctl