Porting a WPF application to Avalonia has never been a simple search-and-replace exercise.
WPF and Avalonia share more in common than almost anything else in the .NET UI ecosystem, but they are not identical. That difference is where the real work lives. Depending on the size of your application, the age of the codebase, and the third-party dependencies involved, a migration can be a focused weekend project or a serious engineering effort that spans several sprints.
AI can now help with a lot of that work.
The latest update to the Avalonia Build MCP server gives AI coding agents a structured way to analyse WPF projects, recommend the right migration path, and guide the port using Avalonia-specific migration tools. Instead of relying on generic model knowledge or a handful of pasted documentation links, your assistant can call focused tools that reflect how real WPF applications are actually moved to Avalonia.
That matters because the first question in any serious WPF migration is not “which files do we rename?”
It is this: should this application become a native Avalonia application, or should it move to Avalonia XPF first?
Start with the Right Migration Path
Before touching code, it is worth being honest about the destination.
If you have not yet decided where your WPF application should be heading, start with our recent piece on WPF modernisation in 2026. It walks through the main options and helps you decide whether your application should stay on WPF, move to Avalonia XPF for a lower-risk route to cross-platform delivery, or be rewritten as a native Avalonia application.
That decision shapes everything that follows.
We have helped many organisations make this transition. The sustained demand from customers wanting to bring WPF applications to macOS, Linux, and beyond is one of the reasons we built Avalonia XPF in the first place. For large WPF codebases, particularly those with third-party controls, custom controls, and a long tail of framework-specific behaviours, XPF is often the safest path.
This post is for teams that are ready to begin the migration conversation with an AI coding agent in the loop.
If you want the deeper manual playbook, our expert guide to porting WPF applications to Avalonia covers the strategy in detail, while the migration documentation covers the mechanical differences between the frameworks.
What has changed is that your AI assistant can now use that migration knowledge more effectively.
Why MCP Helps with WPF Migration
MCP, or Model Context Protocol, gives AI coding assistants a way to call structured tools on your behalf.
That means your assistant does not have to rely only on what it learned during training, or on whatever happens to fit into the chat window. It can search current Avalonia documentation, inspect the shape of your project, retrieve focused WPF-to-Avalonia mapping guidance, and follow a migration workflow designed around real applications rather than toy examples.
The Avalonia Build MCP server is free, hosted, and quick to connect. Once configured, your agent can use Avalonia migration guidance directly from MCP-compatible tools such as Claude Code, Cursor, GitHub Copilot, Rider AI Assistant, Windsurf, Visual Studio, VS Code, Gemini CLI, and other environments with compatible MCP tool support.
There is one important practical point. The Build MCP server provides migration workflow tools and Avalonia guidance. Your coding agent, and model provider control how project context is read and what is sent to the model. If you are working on confidential or commercially sensitive code, review your assistant’s configuration and your organisation’s AI usage policies before starting a migration.
AI can accelerate the port, but your engineering controls still matter.
What Changed in the Build MCP Server
Previously, the WPF migration workflow lived in a single MCP prompt. That worked well in tools such as Claude Code and Cursor, but many editors do not expose MCP prompts directly in their interface. As a result, developers using other environments could not always invoke the workflow reliably.
We have moved the workflow into MCP tools instead.
That makes the experience much more portable. Tools are easier for MCP-compatible assistants to discover and call, which means the migration workflow has a much better chance of appearing when you ask your assistant to help port a WPF application.
The workflow now follows a clearer path.
You start with analyze_wpf_project. This guides the assistant through scanning your solution and project files, looking at target frameworks, WPF references, third-party control suites, MVVM frameworks, platform-specific APIs, P/Invoke calls, and other signals that affect the migration strategy. The goal is to recommend the right route before the code starts changing.
If the application is a strong fit for Avalonia XPF, the assistant can use migrate_to_xpf. This walks through a drop-in migration path, including NuGet feed setup, SDK changes, licence configuration, common version conflicts, and the first compatibility issues teams often encounter.
If the application is heading towards a native Avalonia rewrite, the assistant can use migrate_to_avalonia. This provides a phased playbook covering project setup, file migration, build validation, testing, and the runnable-baseline technique we use on customer migration projects. The aim is to keep the application moving forward in working increments, rather than disappearing into a long rewrite that only becomes testable at the end.
When the assistant needs specific conversion guidance, it can call lookup_wpf_to_avalonia_mapping. This acts as a focused reference shelf for controls, properties, bindings, styling, events, templates, custom controls, and common migration gotchas. Instead of dumping a giant reference document into the context window, the assistant retrieves the mapping it needs at the point it needs it.
Avalonia or XPF?
The most valuable part of the workflow is not the mechanical conversion. It is forcing the right strategic question before the port begins.
Should this application become native Avalonia now, or should it move through Avalonia XPF first?
For straightforward WPF applications without heavy third-party control dependencies, native Avalonia is often the right destination. You get Avalonia’s modern control set, FluentTheme, compiled bindings, styling system, and deployment across Windows, macOS, Linux, mobile, browser, and embedded targets.
A native port is also a chance to modernise the application properly. Many WPF codebases have grown organically over a decade or more. Moving to Avalonia can be the right moment to tidy view models, remove obsolete patterns, improve testability, and build a UI layer that is easier to evolve.
That said, a full native port benefits from discipline. The fastest route is rarely to convert every file and hope for the best. A small window that builds and runs on macOS and Linux is more valuable than a beautifully converted application that does not start. The native migration workflow is designed around that reality.
Avalonia XPF is often the better starting point for more complex applications.
If your WPF codebase is large, uses substantial third-party controls, depends heavily on WPF behaviours such as DependencyProperty, VisualStateManager, DataTrigger, custom controls, or deep code-behind integration, XPF can reduce risk dramatically. Rather than rewriting the UI upfront, you can take much of the existing WPF application cross-platform while preserving the familiar programming model.
In supported scenarios, existing XAML, controls, dependency properties, and code-behind can continue to work with far fewer changes than a native rewrite would require. Teams can ship cross-platform earlier, validate commercial demand, and then gradually move selected screens or components to native Avalonia when the business case is clear.
That is why the Build MCP server does not treat native Avalonia as the only correct answer.
Sometimes the best migration is the one that gets the product into users’ hands with the least risk.
We would rather help you ship.
Where AI Actually Helps
AI is useful in a WPF migration because much of the work is tedious, repetitive, and easy to get nearly right.
Renaming .xaml files to .axaml, replacing pack:// URIs with avares://, translating styles, converting visibility patterns, updating bindings, replacing WPF-specific controls, and rewriting dependency property declarations can consume a large amount of engineering time.
None of that work is glamorous. All of it needs to be done carefully.
This is where the MCP workflow helps. The assistant can pull focused mapping guidance at each step, apply it to the code in front of it, and keep the migration moving without forcing a developer to manually cross-check the same documentation every few minutes.
It does not remove the need for engineering judgement.
You still need a developer in the seat. Architectural decisions, custom control strategy, third-party dependency choices, performance trade-offs, and product-level decisions cannot be outsourced to a code assistant. The best way to think about the workflow is as a fast pair programmer with access to Avalonia-specific migration guidance.
It can do a lot of the mechanical work.
You decide what the application should become.
Getting Started
The Avalonia Build MCP server is free to use and runs as a remote endpoint, so there is nothing to install locally.
The documentation includes setup instructions for VS Code, Visual Studio, Rider, Cursor, Windsurf, Claude Code, Claude Desktop, Gemini CLI, and other MCP-compatible tools.
Once connected, open your WPF solution and ask your assistant:
Analyse this WPF solution and recommend whether I should migrate it to native Avalonia or Avalonia XPF.
That gives the assistant the right starting point. It can inspect the project structure, identify migration risks, and recommend a route before attempting code changes.
If your migration is too large, or too important to leave entirely to an assistant, we can help there too. Our team has helped customers move substantial WPF applications to Avalonia and Avalonia XPF, including codebases with custom controls, third-party dependencies, and long-lived architectural patterns.
The new MCP workflow is there to make the path clearer, whichever route you choose. To explore more ways Avalonia works with AI coding tools, visit our AI page.
Get your WPF application running where your users need it.