LLM 控制（MCP）

Wails v3 内置了模型上下文协议（MCP）服务器，LLM 智能体（Claude Code、IDE 助手或任何 MCP 客户端）可通过它检查、测试和操控正在运行的 Wails 应用。

如需自动化项目生命周期，请使用单独的wails3 mcp CLI 服务器。智能体可通过它检查和初始化项目、运行诊断、启动构建和开发任务、生成绑定、运行指定的 Taskfile 任务，以及获取有界的任务输出。默认情况下，CLI 服务器仅限访问当前目录，且不提供任意 shell 命令执行功能。有关传输、身份验证和工具的详细信息，请参阅CLI MCP 文档。

启用后，连接到应用的智能体可以：

• 列出并控制窗口——调整大小和位置、聚焦、全屏显示、打开开发者工具、重新加载等
• 检查 DOM——查询元素、获取 HTML、生成结构快照
• 执行 JavaScript——在任意窗口内运行任意代码并获取结果
• 模拟用户输入——通过带动画效果的屏幕光标呈现鼠标移动、单击、拖动和滚动，让你可以看到智能体的操作过程
• 输入文本和按键——生成逼真的逐字符事件，可用于 React 受控输入框
• 调用已绑定的 Go 方法，以及发出或等待应用事件

工作原理

仅当存在mcp构建标签时，MCP 服务器才会被编译到应用中。如果没有该标签，服务器代码将完全不包含在二进制文件中——没有运行时开销，不会开放端口，也不会增加攻击面。

存在该标签时，服务器会在App.Run()中自动启动，默认绑定到127.0.0.1:9099，并记录其端点。无需编写任何用户代码。

教程

第1步——编写常规 Wails 应用

MCP 无需导入或注册。按通常方式创建应用即可：

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)
    }
}

第2步——使用mcp标签构建或运行

# Development
WAILS_MCP=1 wails3 dev

# Production build
WAILS_MCP=1 wails3 build

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

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

应用启动时会记录 MCP 端点：

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

第3步——连接客户端

服务器使用MCP Streamable HTTP 传输。可使用任何兼容 MCP 的客户端连接。

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

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

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

http://127.0.0.1:9099/mcp

第4步——运行测试会话

让智能体操作并测试你的应用。下面是一些示例提示词：

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.

配置

所有配置均通过环境变量完成，无需更改代码。

示例——自定义端口和60秒超时时间：

WAILS_MCP=1 WAILS_MCP_PORT=9200 WAILS_MCP_TIMEOUT=60000 wails3 dev

可用工具

多窗口支持

所有对窗口执行操作的工具都接受一个可选的window参数，其中包含窗口的名称（通过WebviewWindowOptions.Name设置）。如果省略该参数，工具会以当前获得焦点的窗口为目标；如果没有窗口获得焦点，则以第一个窗口为目标。

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

选择元素

鼠标和键盘工具接受以下任一方式：

• CSS 选择器——selector: "#submit-btn"（元素会自动滚动到可见区域）
• 坐标——x: 400, y: 300（相对于视口的 CSS 像素）

对于拖动操作，请分别添加前缀from_和to_：

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

安全性

• 默认情况下，服务器绑定到127.0.0.1。浏览器来源必须是 HTTP(S) 环回来源；不透明（null）、格式错误及外部来源均会被拒绝。
• 仍然支持不带标头的原生 MCP 客户端。未设置WAILS_MCP_TOKEN时，本地进程和获准的本地浏览器来源会受到信任；来源检查并非身份验证。请设置一个高熵令牌，要求所有/mcp调用都进行持有者身份验证。在客户端的Authorization: Bearer <token>标头中配置同一个令牌。预检请求无需提供该令牌。
• /eval-result回调使用每次求值时生成的不可预测 ID，而不使用客户端持有者令牌，因此仍可兼容 WebView 结果传递。
• 生产构建不应包含mcp标签。只有明确设置WAILS_MCP=1时，Wails CLI 才会添加该标签；默认的wails3 build不含任何服务器代码。
• 如果需要在非环回接口上公开服务器（例如用于局域网测试），请设置WAILS_MCP_HOST=0.0.0.0和高熵WAILS_MCP_TOKEN；未设置令牌时，服务器将无法启动。在不受信任的网络上，请使用加密隧道或终止 TLS 的代理，因为内置监听器使用 HTTP。

示例应用程序

v3/examples/mcp提供了一个演示所有工具的完整试验场应用程序。它包括：

• 带有递增和重置按钮的计数器
• 姓名输入框，以及已绑定的 Greet、Add、Shout 方法
• HTML5 拖放源和目标
• 可滚动列表（包含50个项目）
• 事件日志

使用以下命令运行：

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

然后将 Claude Code 或任意 MCP 客户端连接到http://127.0.0.1:9099/mcp，并让它操作该用户界面。

反馈

内置 MCP 服务器是一项实验，其未来方向取决于你的反馈。如果你试用了它，我们很想了解你使用了哪些客户端和工具、你的预期与实际结果，以及让代理操作你的应用程序是否有用——最有价值的报告会准确说明你运行了什么。请在MCP 服务器反馈讨论中告诉我们。