LLM Control (MCP)

Experimental Feature

The built-in MCP server is experimental and the API may change in future releases.

Wails v3 has a built-in Model Context Protocol (MCP) server that lets LLM agents — Claude Code, IDE assistants, or any MCP client — inspect, test, and drive a running Wails application.

When enabled, an agent connected to your app can:

• List and control windows — size, position, focus, fullscreen, devtools, reload, …
• Inspect the DOM — query elements, get HTML, take a structural snapshot
• Evaluate JavaScript — run arbitrary code inside any window and get the result
• Simulate user input — mouse moves, clicks, drags and scrolls rendered with an animated on-screen cursor so you can watch the agent work
• Type and press keys — realistic per-character events that work with React controlled inputs
• Call bound Go methods and emit/await application events

How it works

The MCP server is compiled into your application only when the mcp build tag is present. Without the tag the server code is completely absent from the binary — no runtime overhead, no open ports, no attack surface.

When the tag is present the server starts automatically inside App.Run(), binds to 127.0.0.1:9099 by default, and logs its endpoint. No user code is required.

Tutorial

Step 1 — write a normal Wails application

MCP requires no imports and no registration. Create your app as you normally would:

main.go

package main

import (
    "embed"
    "log"

    "github.com/wailsapp/wails/v3/pkg/application"
)

//go:embed assets
var assets embed.FS

func main() {
    app := application.New(application.Options{
        Name: "My App",
        Assets: application.AssetOptions{
            Handler: application.BundledAssetFileServer(assets),
        },
    })

    app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title: "My App",
        Width: 1024, Height: 768,
    })

    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

Step 2 — build or run with the mcp tag

Wails CLI (recommended)

Set WAILS_MCP=1 and the Wails CLI adds the mcp tag for you:

# Development
WAILS_MCP=1 wails3 dev

# Production build
WAILS_MCP=1 wails3 build

Direct Go

Pass the tag to go run or go build directly:

go run -tags mcp .
go build -tags mcp -o myapp .

Windows (PowerShell)

$env:WAILS_MCP = "1"
wails3 dev
# or
wails3 build

On startup the application logs the MCP endpoint:

INFO MCP server started. Connect MCP clients using the streamable HTTP transport.
     url=http://127.0.0.1:9099/mcp

Step 3 — connect a client

The server speaks the MCP streamable HTTP transport. Connect with any MCP-compatible client.

Claude Code

claude mcp add --transport http my-app http://127.0.0.1:9099/mcp

Then ask Claude to interact with your app:

Click the "Submit" button, then verify a success toast appears.

VS Code (GitHub Copilot)

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcp.enabled": true,
  "mcp": {
    "servers": {
      "my-wails-app": {
        "type": "http",
        "url": "http://127.0.0.1:9099/mcp"
      }
    }
  }
}

Other clients

Point any MCP client that supports the streamable HTTP transport at:

http://127.0.0.1:9099/mcp

Step 4 — run a test session

Ask the agent to exercise your application. Here are some example prompts:

Take a DOM snapshot of the main window.

Click the "Add item" button, type "Hello world" in the input field,
then press Enter and verify the item appears in the list.

Call the bound method main.GreetService.Greet with argument ["World"]
and return the result.

Wait for the event "save:complete" while clicking the Save button.

Configuration

All configuration is via environment variables — no code changes required.

Environment variable	Default	Description
WAILS_MCP	(unset)	Set to 1, true, on or yes to add the mcp build tag automatically when using the Wails CLI.
WAILS_MCP_HOST	127.0.0.1	Interface to bind to. Change only in trusted, isolated networks.
WAILS_MCP_PORT	9099	Port to listen on. Set to 0 for a randomly assigned free port (printed in the log).
WAILS_MCP_TIMEOUT	30000	Default JS evaluation timeout in milliseconds.
WAILS_MCP_HIDE_CURSOR	(unset)	Set to 1 or true to disable the animated cursor overlay.

Example — custom port and a 60-second timeout:

WAILS_MCP=1 WAILS_MCP_PORT=9200 WAILS_MCP_TIMEOUT=60000 wails3 dev

Available tools

Tool	Purpose
app_info	Application information: platform, architecture, all windows, MCP endpoint
windows_list	List all windows with geometry and state
window_control	Focus, resize, move, fullscreen, devtools, reload, set URL, … (22 actions)
js_eval	Evaluate JavaScript in a window (async body, return for value)
dom_html	Get the HTML of the page or a specific element
dom_query	Find elements by CSS selector — tag, text, bounds, visibility
screenshot_dom	Structural snapshot of the visible page (DOM-based, no pixels)
mouse_move	Animate the cursor to a point or CSS selector
mouse_click	Click with the animated cursor (left/right/middle, double-click, modifiers)
mouse_drag	Drag with the animated cursor (supports HTML5 drag-and-drop elements)
mouse_scroll	Scroll at a point or element
keyboard_type	Type text character by character with realistic events
keyboard_press	Press a single key (Enter, Tab, Escape, ArrowDown, …) with optional modifiers
call_bound_method	Call a bound Go service method, e.g. main.GreetService.Greet
emit_event	Emit a Wails application event
wait_for_event	Wait for a Wails application event and return its data

Multi-window support

All tools that act on a window accept an optional window argument containing the window’s name (set via WebviewWindowOptions.Name). When omitted, the tool targets the currently focused window, or the first window if none is focused.

List all windows, then click the "New" button in the window named "editor".

Selecting elements

Mouse and keyboard tools accept either:

• CSS selector — selector: "#submit-btn" (element is scrolled into view automatically)
• Coordinates — x: 400, y: 300 (CSS pixels relative to the viewport)

For drag operations, prefix with from_ and to_:

Drag from selector: ".card" to selector: ".dropzone"

Security

警告

The MCP server gives full programmatic control over your application. Anyone who can reach the port can read the DOM, evaluate JavaScript, click buttons, and call Go methods.

• The server binds to 127.0.0.1 by default and rejects non-local browser origins (DNS-rebinding protection per the MCP spec).
• Production builds should not include the mcp tag. The Wails CLI only adds it when WAILS_MCP=1 is explicitly set, and the default wails3 build has none of the server code.
• If you need to expose the server on a non-loopback interface (e.g. LAN testing), set WAILS_MCP_HOST=0.0.0.0 and ensure your network is trusted.

Example application

A complete playground application demonstrating all tools is available at v3/examples/mcp. It includes:

• Counter with increment/reset buttons
• Name input with Greet, Add, Shout bound methods
• HTML5 drag-and-drop source and target
• Scrollable list (50 items)
• Event log

Run it with:

cd v3/examples/mcp
go run -tags mcp .

Then connect Claude Code or any MCP client to http://127.0.0.1:9099/mcp and ask it to exercise the UI.

Feedback

The built-in MCP server is an experiment, and your feedback decides where it goes. If you try it, we’d love to hear which client and tools you used, what you expected and what actually happened, and whether letting an agent drive your app was useful — the most useful reports say exactly what you ran. Tell us in the MCP Server feedback discussion.