使用说明

tauri插件mcp

使像Claude这样的人工智能助手能够与您的Tauri桌面应用程序进行交互，以进行测试和自动化。

Claude代码插件

此回购可兼作 Claude代码插件.完全工作设置的三个步骤：

1.添加市场并安装插件

/plugin marketplace add DaveDev42/tauri-plugin-mcp
/plugin install tauri-mcp

在安装过程中，系统会提示您：

Tauri应用程序目录：相对于项目根的路径（例如。 . 对于单个应用存储库， apps/desktop 对于monorepos）。

2.运行安装程序命令

/tauri-mcp:install

此功能会自动编辑您的Tauri项目： Cargo.toml, src-tauri/src/lib.rs能力， package.json，前端入口(main.tsx/main.ts)，以及 .gitignore。每次写入都会被预览为差异，需要您先确认。

3.重新启动克劳德代码

这个 tauri-mcp MCP服务器在重新启动时注册。证实 /mcp --它应该显示 tauri-mcp 连接。您现在可以拨打电话 start_session, snapshot, click等等。

为什么重启？

MCP服务器在Claude Code启动时注册。安装插件或更改 tauri_app_dir 两者都需要重新启动才能生效。

插件提供了什么

MCP服务器作为一个独立的单文件包提供(packages/tauri-mcp/dist/index.js)所有依赖项都内联--否 node_modules 在目标机器上需要，因此安装在macOS、Linux和Windows上的工作方式相同。

内容包括：

组件	描述
MCP服务器	独立 `tauri-mcp` 捆绑包（14个用于应用生命周期、UI交互、屏幕截图、日志记录的工具）
`/tauri-mcp:install` 命令	编辑Tauri项目以连接插件的一次性安装程序
`tauri-qa` 技能	QA编排——准备测试场景，委托给QA代理，验证结果
`tauri-debug` 技能	常见MCP会话问题的诊断决策树
`qa-tester` agent	使用MCP工具执行测试场景的测试代理（俳句）
QA验证挂钩	验证QA PASS结果是否包括实际的工具调用证据

特性

跨平台：Windows（命名管道）+macOS/Linux（Unix套接字）
无CDP依赖关系：适用于所有WebView后端，包括macOS WKWebView
MCP集成：与Claude Code和其他MCP客户端直接集成
多窗口支持：按标签定位任何窗口；自动桥式注射
统一日志记录：构建、运行时、控制台和网络日志，并进行过滤
动态端口分配：自动随机分配端口以避免冲突

先决条件

Node.js >= 18
陶里 v2.x
pnpm （推荐）或npm
锈货物

快速开始

[]添加Rust插件 src-tauri/Cargo.toml
[]安装npm包： pnpm add github:DaveDev42/tauri-plugin-mcp#main
[]在中注册插件 src-tauri/src/lib.rs
[]添加 mcp:default 许可
[]在中初始化网桥 main.tsx
[]创建 .mcp.json 克劳德代码

安装

1.Rust插件（src-tauri/Cargo.toml）

[dependencies]
tauri-plugin-mcp = { git = "https://github.com/DaveDev42/tauri-plugin-mcp" }

2.前端API（package.json）

pnpm add github:DaveDev42/tauri-plugin-mcp#main

3.MCP服务器

MCP服务器二进制文件(tauri-mcp)安装后自动可用。无需额外设置。

设置

1.注册插件（src-tauri/src/lib.rs）

pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_mcp::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

2.添加权限

选项A：在tauri.conf.json或config/*.json中（推荐）

{
  "security": {
    "capabilities": [{
      "identifier": "main-capability",
      "windows": ["main"],
      "permissions": ["core:default", "mcp:default"]
    }]
  }
}

选项B：单独文件（src-tauri/capabilities/default.json）

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": ["core:default", "mcp:default"]
}

3.初始化网桥（main.tsx）

// Initialize MCP bridge for E2E testing (dev mode only)
if (import.meta.env.DEV) {
  import('tauri-plugin-mcp').then(({ initMcpBridge }) => {
    initMcpBridge().catch(err => {
      console.warn('[MCP] Bridge initialization failed:', err);
    });
  });
}

安全生产设置（可选依赖项）

上述基本设置包括所有版本中的MCP。对于生产应用程序，您可能需要MCP 只在发展中 并且完全从发布二进制文件中删除。

这种方法使用Cargo的可选依赖特性，因此只有在明确请求时才会编译插件。

1.货物可选依赖项（src-tauri/Cargo.toml）

[features]
default = []
dev-tools = ["dep:tauri-plugin-mcp"]

[dependencies]
tauri-plugin-mcp = { git = "https://github.com/DaveDev42/tauri-plugin-mcp", optional = true }

2.有条件的插件注册（src-tauri/src/lib.rs）

pub fn run() {
    let mut builder = tauri::Builder::default();

    #[cfg(feature = "dev-tools")]
    {
        builder = builder.plugin(tauri_plugin_mcp::init());
    }

    builder
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

3.能力文件拆分

分开 mcp:default 将其转换为自己的功能文件，以便在构建时进行切换。

capabilities/default.json --始终处于活动状态，无MCP权限：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": ["core:default"]
}

capabilities/.dev-tools.json.disabled --MCP权限模板（跟踪git）：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "dev-tools",
  "windows": ["main"],
  "permissions": ["mcp:default"]
}

capabilities/dev-tools.json --添加到 .gitignore （在构建时生成）：

# Dev-tools capability (generated from .disabled at build time)
src-tauri/capabilities/dev-tools.json

4.build.rs——条件能力管理

build.rs 启用该功能时将模板复制到位，否则将其删除：

fn main() {
    let dev_tools_cap = std::path::Path::new("capabilities/dev-tools.json");
    let source_path = std::path::Path::new("capabilities/.dev-tools.json.disabled");

    if std::env::var("CARGO_FEATURE_DEV_TOOLS").is_ok() {
        // Copy .disabled → active (skip if already identical to avoid rebuild churn)
        let should_copy = if dev_tools_cap.exists() {
            std::fs::read(source_path).ok() != std::fs::read(dev_tools_cap).ok()
        } else {
            true
        };
        if should_copy {
            std::fs::copy(source_path, dev_tools_cap)
                .expect("Failed to copy dev-tools capability file");
        }
    } else if dev_tools_cap.exists() {
        std::fs::remove_file(dev_tools_cap).ok();
    }

    tauri_build::try_build(
        tauri_build::Attributes::default()
    ).expect("Failed to build tauri");
}

5.开发脚本（package.json）

{
  "scripts": {
    "dev": "tauri dev --features dev-tools"
  }
}

现在 pnpm dev 启用MCP，同时 tauri build （没有该功能）生成了一个无MCP代码的干净版本。

注：前端桥梁防护装置(import.meta.env.DEV)从基本设置仍然适用——即使插件在运行时以某种方式存在，它也会阻止网桥初始化。

MCP服务器配置

注：如果您安装了 Claude代码插件，MCP服务器已自动配置。插件在安装过程中会提示输入Tauri应用程序目录。本节适用于不使用插件的手动设置。

增添 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": "."
      }
    }
  }
}

注： pnpm用户还可以使用 pnpx tauri-mcp 或 pnpm exec tauri-mcp.

Monorepo配置

如果Tauri应用程序位于子目录中（例如。， apps/desktop)，set TAURI_APP_DIR:

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": "./apps/desktop"
      }
    }
  }
}

多个Tauri应用程序

对于具有多个Tauri应用程序的monorepos，请为每个应用程序运行一个单独的MCP服务器实例：

{
  "mcpServers": {
    "tauri-desktop": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": { "TAURI_APP_DIR": "./apps/desktop" }
    },
    "tauri-kiosk": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": { "TAURI_APP_DIR": "./apps/kiosk" }
    }
  }
}

工具按服务器名称分隔： mcp__tauri-desktop__snapshot, mcp__tauri-kiosk__snapshot等等。

可用工具

会话生命周期

工具	参数	说明
`get_session_status`	`probe_bridge?: boolean`	检查会话（应用程序）状态；随着 `probe_bridge: true`，包括每个窗口桥的健康状况
`start_session`	`wait_for_ready?: boolean`, `timeout_secs?: number`, `features?: string[]`, `devtools?: boolean`	开始会话（通过以下方式启动Tauri应用程序 `pnpm tauri dev`)
`stop_session`	-	停止会话（杀死应用程序进程树）

窗口管理

工具	参数	说明
`list_windows`	-	列出所有打开的窗口，包括标签、标题、焦点状态和桥接状态
`focus_window`	`window: string`	按标签聚焦特定窗口

交互

所有交互工具都接受可选 window 参数以针对特定窗口（默认为聚焦窗口）。

工具	参数	说明
`snapshot`	`window?`	获取带有参考号的可访问性树 `click`/`fill`
`click`	`ref?: number`, `selector?: string`, `window?`	通过ref或CSS选择器单击元素
`fill`	`ref?: number`, `selector?: string`, `value: string`, `window?`	填写输入字段
`press_key`	`key: string`, `window?`	按键盘键（例如“Enter”、“Tab”）
`navigate`	`url: string`, `window?`	导航到URL
`screenshot`	`window?`	通过原生操作系统截图
`evaluate_script`	`script: string`, `window?`	在webview中执行JavaScript

可观测性

工具	参数	说明
`get_logs`	`filter?: string[]`, `limit?: number`, `clear?: boolean`, `window?`	具有源代码/级别过滤的统一日志访问（构建、运行时、控制台、网络）
`get_restart_events`	`limit?: number`, `clear?: boolean`, `window?`	使用触发文件获取最近的应用程序重启/重新加载事件

使用 `features` 参数

要使用Cargo功能启动：

start_session({ features: ["my_feature"] })

这运行： pnpm tauri dev --features my_feature

用法示例

典型测试工作流程：

1. start_session({ timeout_secs: 120 })
2. snapshot()           # Get element refs
3. click({ ref: 5 })    # Click button by ref
4. fill({ selector: "input[name='email']", value: "test@example.com" })
5. screenshot()         # Verify result
6. stop_session()

运作原理

Claude Code <-> MCP Server <-> Socket <-> Tauri Plugin <-> JS Bridge <-> Your App

Rust插件 创建IPC服务器（Unix套接字或Windows命名管道）
MCP 服务器 连接到IPC并向Claude公开工具
JS大桥 (initMcpBridge())在WebView中启用DOM操作

套接字路径

Unix: {project_root}/.tauri-mcp.sock
视窗: \\.\pipe\tauri-mcp-{hash} （哈希值来源于项目路径）

TCP传输（通过SSH隧道远程访问）

默认情况下，插件通过本地命名管道（Windows）或Unix套接字（macOS/Linux）进行通信。命名管道和Unix套接字是机器本地的——它们不能跨越网络边界。使用可选 TCP传输 当Tauri应用程序在与Claude Code不同的机器上运行时（例如远程驱动的信息亭PC或CI运行器）。

当 TAURI_MCP_TCP 未设置，行为逐字节不变——现有的管道/套接字是唯一的传输。

应用端（Rust插件）

集 TAURI_MCP_TCP 启动应用程序时。该插件绑定TCP侦听器除了现有的管道/插座（管道永远不会被拆除）。

TAURI_MCP_TCP=127.0.0.1:19878   # bind on loopback only (recommended — reach via SSH tunnel)
TAURI_MCP_TCP=19878              # shorthand — same as 127.0.0.1:19878
TAURI_MCP_TCP=0.0.0.0:19878     # bind all interfaces (only if network is fully trusted)

插件在启动时记录绑定地址：

[tauri-plugin-mcp] TCP transport listening on 127.0.0.1:19878

MCP服务器端（节点）

设置相同 TAURI_MCP_TCP MCP服务器进程上的env。它拨打TCP而不是本地管道/套接字，并跳过所有本地管道发现：

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": ".",
        "TAURI_MCP_TCP": "127.0.0.1:19878"
      }
    }
  }
}

工作示例——通过SSH隧道远程信息亭

在远程机器上 （使用TCP传输运行的kiosk应用程序）：

TAURI_MCP_TCP=127.0.0.1:19878 pnpm tauri dev
# → [tauri-plugin-mcp] TCP transport listening on 127.0.0.1:19878

在开发机器上 （通过SSH转发端口）：

ssh -L 19878:127.0.0.1:19878 kiosk-host

MCP服务器 .mcp.json （dev机器，通过隧道连接）：

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": "/path/to/local/project",
        "TAURI_MCP_TCP": "127.0.0.1:19878"
      }
    }
  }
}

start_session / stop_session 在TCP模式下不可用（MCP服务器无法启动或终止远程计算机上的进程）。使用交互和可观察性工具(snapshot, click, get_logs等等）来驱动已经运行的应用程序。

故障排除

“MCP网桥未初始化”

JS桥没有运行。检查：

initMcpBridge() 在前端代码中调用
应用程序正在开发模式下运行(import.meta.env.DEV)
检查浏览器控制台是否存在初始化错误

套接字连接失败

确保应用程序正在运行(start_session 第一）
在Windows上，检查日志中的管道路径： [tauri-plugin-mcp] full_path: \\.\pipe\tauri-mcp-XXXXX
在Unix上，检查 .tauri-mcp.sock 存在于项目根目录中

应用程序启动超时

增加 timeout_secs （默认值：60）
检查是否 pnpm tauri dev 手动工作
在终端输出中查找构建错误

快照返回空

等待应用程序完全加载（使用 wait_for_ready: true)
检查网桥是否已初始化（查找 [MCP] 登录控制台）

发展

克隆后， pnpm install 自动配置git钩子并构建项目。

这个 dist/ 目录被提交到仓库，以便基于git的安装(pnpm add github:...)无需构建步骤即可工作。预提交钩子验证 dist/ 与TypeScript源代码保持同步——如果钩子阻止了你的提交，运行：

pnpm build
git add packages/*/dist/

然后重试您的提交。

许可证

麻省理工学院或阿帕奇-2.0