XamlMcp

XamlMcp

XamlMcp is an open-source XAML MCP server and AI inspection toolkit for Avalonia, WPF, WinUI 3, and .NET MAUI. It lets Claude Code, Codex, GitHub Copilot, and other MCP clients inspect and drive a running application: walk the visual or logical tree, read and write properties, inspect styles and resources, capture screenshots, send input, invoke commands and automation patterns, and observe changes over an authenticated local transport.

See the XamlMcp installation and configuration guide for a focused setup path across supported frameworks and AI clients.

The current release is 1.0.0-preview.3. It supports Avalonia, modern .NET WPF, self-contained unpackaged WinUI 3, and .NET MAUI on Windows and Android. Protocol version 2 is stable. Native MAUI nodes, iOS, and Mac Catalyst are unsupported.

See the changelog for user-facing release history and the framework feature and tool matrix for per-tool support and capability limits. The preview release guide explains the package roles, installation options, and verification commands.

Packages

Install

Prerequisite: the app you inspect can target .NET 8 or later, but the xamlmcp tool (and building this repo or the sample from source) needs the .NET 10 SDK/runtime.

Add the agent package for your UI framework:

dotnet add package XamlMcp.Avalonia --version 1.0.0-preview.3

dotnet add package XamlMcp.Wpf --version 1.0.0-preview.3 dotnet add package XamlMcp.WinUI --version 1.0.0-preview.3 dotnet add package XamlMcp.Maui --version 1.0.0-preview.3

The agent's floor is Avalonia 11.3.18. If your project pins older references (the current avalonia.app template pins 11.3.0) restore fails with a NU1605 package-downgrade error — bump your Avalonia.* package references to at least 11.3.18.

Install the MCP server tool:

dotnet tool install --global XamlMcp.Server --version 1.0.0-preview.3

You can also run the server without a global installation:

dnx XamlMcp.Server@1.0.0-preview.3

Attach the Avalonia agent

Two entry points provide explicit diagnostic opt-in. Nothing listens unless you enable the agent per build (option B) or per launch (option A):

using XamlMcp.Avalonia;

// Option A - fluent, in BuildAvaloniaApp. Compiled in, but INERT unless the // XAML_MCP=1 environment variable is set when the app launches. public static AppBuilder BuildAvaloniaApp() => AppBuilder.Configure () .UsePlatformDetect() .AttachXamlMcp();

// Option B - on the Application instance (e.g. in OnFrameworkInitializationCompleted). // Marked [Conditional("DEBUG")]: the CALL SITE disappears from YOUR Release builds. public override void OnFrameworkInitializationCompleted() { this.AttachXamlMcp(); base.OnFrameworkInitializationCompleted(); }

Why two shapes? [Conditional] requires a void method, so the fluent AppBuilder overload can't use it and gates on the environment variable instead. And why not a plain #if DEBUG inside the package? That would gate on how *this package* was compiled at pack time and could never see *your* app's configuration at all. Both overloads instead gate on your build configuration or your launch environment.

Know the difference: option B's call is gone from your Release binaries; option A's code ships in Release but stays inert unless XAML_MCP=1 is present at launch — anyone who controls the launch environment can enable it. If you need hard exclusion with the fluent shape, wrap the .AttachXamlMcp() line in your own #if DEBUG.

Attach the WPF agent

Call the extension on the WPF Application in OnStartup:

using System.Windows;

using XamlMcp.Wpf;

public partial class App : Application { protected override void OnStartup(StartupEventArgs e) { this.AttachXamlMcp(); base.OnStartup(e); } }

The WPF method is [Conditional("DEBUG")], so the call site disappears from the consuming app's Release build. There is no environment-enabled WPF overload. The agent uses the Application.Dispatcher that performs attachment. Windows and controls owned by secondary WPF UI threads are excluded.

Attach the WinUI agent

Attach on the WinUI UI thread, explicitly register each Window, and keep the calls inside the application's diagnostic build gate:

using Microsoft.UI.Xaml;

using XamlMcp.WinUI;

public partial class App : Application { private WinUiXamlMcpSession? _xamlMcp; private IDisposable? _windowRegistration;

protected override void OnLaunched(LaunchActivatedEventArgs args) { var window = new MainWindow(); #if DEBUG var session = WinUiXamlMcp.Attach(); _xamlMcp = session; _windowRegistration = session.RegisterWindow(window); window.Closed += async (_, _) => { _windowRegistration?.Dispose(); await session.DisposeAsync(); }; #endif window.Activate(); } }

Attach() is not conditionally compiled: the caller owns the #if DEBUG or equivalent diagnostic gate. One session supports one DispatcherQueue and explicitly registered windows on that queue. The supported floor is Windows App SDK 2.3.1, target framework net8.0-windows10.0.19041.0, Windows 10 1809 (10.0.17763.0), and win-x64.

WinUI support is unpackaged. Use WindowsPackageType=None, WindowsAppSDKSelfContained=true, and publish to a fresh directory:

dotnet publish MyWinUiApp.csproj -c Release -r win-x64 --self-contained true -o artifacts/winui

The publish output must retain the generated .xbf and .pri resources. MSIX/package identity, certificates, Store distribution, XAML Islands, and multiple UI threads are unsupported.

Attach the .NET MAUI agent

Call UseXamlMcp() while building the MAUI app, inside the application's diagnostic build gate:

using XamlMcp.Maui;

public static MauiApp CreateMauiApp() { var builder = MauiApp.CreateBuilder() .UseMauiApp ();

#if DEBUG builder.UseXamlMcp(); #endif

return builder.Build(); }

The same package and UseXamlMcp() call work in unpackaged Windows applications and debuggable Android applications on MAUI 10.0.80. The package does not inspect the consumer's configuration, so the caller must own the #if DEBUG or equivalent diagnostic gate. Android projects must set SupportedOSPlatformVersion to 24.0 or later. Screenshots require API 26 or later.

On Windows, the agent writes a discovery file under %LOCALAPPDATA%/XamlMcp/instances/ (override the directory with XAML_MCP_DIR) and serves JSON-RPC 2.0 on a current-user named pipe. On Android, it listens only on device loopback and stores a per-launch descriptor in app-private storage. The server reads that descriptor through debuggable run-as access and creates an owned adb forward only while connecting. Both transports require the per-launch token before any inspection call.

To discover an Android app, pass its application ID to the MCP server. Select a device explicitly when more than one authorized device is online:

claude mcp add xamlmcp -- xamlmcp --android-package dev.example.app --android-device emulator-5554

The Windows build prerequisites are the .NET 10 SDK and MAUI Windows workload. Android also requires the .NET Android workload and Android SDK platform tools (adb). iOS and Mac Catalyst are unsupported.

Connect an AI client

XamlMcp is a local stdio MCP server. Claude Code or Codex starts it when the client session needs it; you do not run a persistent server process.

This repository includes portable project configuration for both clients:

• .mcp.json configures Claude Code.
• .codex/config.toml configures Codex in a trusted checkout.

Both configurations run the pinned preview directly from NuGet with dnx, so they require the .NET 10 SDK but no global tool installation. After cloning the repository, open a new client session and verify the registration:

claude mcp get xamlmcp

codex mcp get xamlmcp

To register the pinned preview for your user account or from another project, run:

claude mcp add --scope user xamlmcp -- dnx XamlMcp.Server@1.0.0-preview.3

codex mcp add xamlmcp -- dnx XamlMcp.Server@1.0.0-preview.3

Alternatively, install the tool globally and register its xamlmcp command:

dotnet tool install --global XamlMcp.Server --version 1.0.0-preview.3

claude mcp add --scope user xamlmcp -- xamlmcp codex mcp add xamlmcp -- xamlmcp

If a client already has a server named xamlmcp, remove or update that entry before adding the new one. Use claude mcp remove xamlmcp --scope or codex mcp remove xamlmcp as appropriate.

Launch an instrumented application next. Set XAML_MCP=1 when using Avalonia's fluent attachment form. Then ask the client to call `list-apps` → `attach(instanceId)` → any tool below. Integer PID attach remains a Windows desktop compatibility path.

| dialog-act | Driver, opt-in: act on it — set-file-name, `accep