Netwright MCP Server

Netwright

Playwright-style automation for .NET desktop apps. Netwright is an MCP server that lets AI agents see and operate WPF, WinForms and WinUI apps: they launch your project, read the UI as compact text, act without stealing your mouse, verify the result, and turn the verified flow into a regression test.

Formerly WPF-MCP. Version 2.0 is a rewrite; see Migrating from WPF-MCP 1.x.

> desktop_app action=launch project=src/Orders/Orders.csproj
Launched Orders.exe (pid 9120, WPF, launched by Netwright)
- window "Orders" [e1]

> desktop_snapshot
- window "Orders" [e1]
  - textbox "Customer" [e4] #txtCustomer
  - combobox "Country" [e5] #cmbCountry collapsed
  - checkbox "Accept terms" [e6] #chkTerms unchecked
  - button "Save" [e7] #btnSave disabled

> desktop_set_state target=#chkTerms checked=true
checked checkbox "Accept terms" [e6] #chkTerms
~ checkbox "Accept terms" [e6] #chkTerms checked
~ button "Save" [e7] #btnSave

> desktop_click target=#btnSave
clicked button "Save" [e7] #btnSave
+ window "Confirm" [e9] modal
  + text "Save order 42?"
  + button "Yes" [e10]

Why Netwright

• Made for .NET apps. Works with WPF, WinForms (.NET and .NET Framework 4.x) and WinUI/MAUI through UI Automation. It launches straight from a .csproj, captures stdout/stderr and Trace output, and reports crashes with the exception and stack trace.
• Cheap in tokens.
  • Snapshots are filtered to what an agent needs: unnamed layout panes are collapsed, and grids are summarized row by row.
  • Actions answer with a Change Report of what appeared, disappeared or changed, so the agent rarely needs another snapshot.
  • Refs (e12) stay valid across snapshots.
• Stays out of your way. Actions run in the background through UI Automation patterns, so you keep working while the agent tests. Key presses and right-clicks are explicit, briefly take focus, and give it back.
• Reliable by default.
  • Every action waits until its target is enabled and on screen.
  • It then waits for the UI to settle, so async screens don't need sleeps.
  • Failures come back as error codes with a hint about what to do next.
• From exploration to regression tests. desktop_expect verifies state, and desktop_export_test turns the session into a C# test on Netwright.Testing (xUnit, NUnit or MSTest).

Benchmark

Same scenarios, same Fixture App, same token encoding for every server (full methodology and all numbers in benchmarks/results):

¹ Windows-MCP summarizes the whole desktop instead of the app's UI tree; its grid snapshot does not include the rows. ² Its actions work at screen coordinates with the real mouse, so scripted flows were not run.

Tokens are counted with o200k_base as a proxy for Claude's tokenizer. Netwright's actions are slower per call: the form flow takes ~1.8 s against ~0.6 s, because each action waits for the UI to settle. In exchange the response already contains the result, so the agent needs fewer calls and far fewer tokens.

Install

Requires Windows 10/11 and the .NET 10 SDK. Your apps can target any .NET or .NET Framework version.

Claude Code

claude mcp add netwright -- dnx Netwright --yes

Any MCP client (Claude Desktop, Cursor, VS Code, Copilot…)

{
  "mcpServers": {
    "netwright": {
      "command": "dnx",
      "args": ["Netwright", "--yes"]
    }
  }
}

Prefer a global tool? Run dotnet tool install -g Netwright and use "command": "netwright". To restrict which apps an agent may touch, add "--", "--allow", "MyApp*" to the args. See the Integration Guide for all options.

Tools

Full reference: docs/TOOLS_REFERENCE.md.

Supported UI technologies

Other Windows apps (Win32, Qt, Electron…) often work because Netwright speaks plain UI Automation, but they are not supported.

Automation works best when your app sets AutomationProperties.AutomationId (WPF/WinUI) or Name (WinForms) on the controls you care about. See Making your app automation-friendly.

Regression tests without an agent

[Fact]
public async Task Saving_an_order_asks_for_confirmation()
{
    await using var app = await DesktopApp.LaunchProjectAsync(@"..\..\..\..\src\Orders\Orders.csproj");

    await app.TypeAsync("#txtCustomer", "Rossi");
    await app.CheckAsync("#chkTerms");
    await app.ClickAsync("#btnSave");

    await app.Expect("window \"Confirm\"").ToBeVisibleAsync();
}

dotnet add package Netwright.Testing. This is the code desktop_export_test writes for you.

How it works

Netwright captures each window with one cached UI Automation query. Windows are found with Win32, only about 20 properties are requested, and offscreen elements are filtered inside the provider. From that capture it renders filtered text, resolves Selectors in memory, and diffs trees by RuntimeId to build Change Reports. Details and measurements: docs/ARCHITECTURE.md. Vocabulary: CONTEXT.md. Decisions: docs/adr.

Migrating from WPF-MCP 1.x

The package is now Netwright (command netwright), replacing WpfMcp.Server (wpf-mcp).

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md. Build and test with .\scripts\build.ps1 -Integration, and measure with .\scripts\benchmark.ps1.

License

MIT