Windows-MCP for Windsurf: Setup & Config

What you can do with Windows-MCP in Windsurf

Choose native Windows automation with optional DOM inspection and documented remote-access controls.

• Perform UI-driven QA tasks through an assistant.
• Expose selected desktop tools to a secured network client.

Before you start: Windows-MCP in Windsurf

• Windows
• Python 3.13+
• uv with uvx
• An MCP-compatible client

This is the documented default stdio launch. English is preferred for App-Tool; disable that tool for other Windows languages. For network access, configure authentication and TLS rather than using an unprotected listener.

Windows-MCP Windsurf configuration

1. Choose Windsurf configuration scope

   For Windows-MCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Windows-MCP to Windsurf

   Use the Windows-MCP entry below in mcpServers. Keep Windows-MCP's documented stdio connection fields and your other Windsurf entries.

3. Check Windows-MCP in Windsurf

   Windows-MCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "Windows-MCP": {
      "command": "uvx",
      "args": [
        "windows-mcp",
        "serve"
      ],
      "env": {}
    }
  }
}

Windows-MCP tools available to Windsurf

Windows-MCP's stored tool list documents 5 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

Screenshot

After refreshing Windows-MCP in Windsurf settings, check Cascade's tool list for Screenshot.

Capture screen imagery; this tool name appears in the README's tool-selection example.

Click

After refreshing Windows-MCP in Windsurf settings, check Cascade's tool list for Click.

Perform a mouse click; this tool name appears in the README's tool-selection example.

Snapshot

After refreshing Windows-MCP in Windsurf settings, check Cascade's tool list for Snapshot.

PowerShell

After refreshing Windows-MCP in Windsurf settings, check Cascade's tool list for PowerShell.

Registry

After refreshing Windows-MCP in Windsurf settings, check Cascade's tool list for Registry.

Expose Windows Registry capability, which the README demonstrates excluding from the enabled tool set.

Windows-MCP: full stored tool descriptions

Troubleshooting Windows-MCP in Windsurf

• Check uvx windows-mcp (from uv, for Python tools) on the machine running Windsurf's MCP integration for Windows-MCP; refresh MCP and inspect Cascade's tools.
• Windows-MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires Windows-side execution even when the assistant runs in WSL.
• Known limitation: Python 3.13+ is required by the documented setup.
• Known limitation: Non-English Windows setups may need the application tool disabled.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions