tauri-plugin-mcp

Plugin de automatización de pruebas para Tauri multiplataforma mediante MCP (Model Context Protocol).

Permite que asistentes de IA como Claude interactúen con tu aplicación de escritorio Tauri para pruebas y automatización.

Plugin de Claude Code

Este repositorio también funciona como un plugin de Claude Code. Tres pasos para una configuración completamente funcional:

1. Añade el marketplace e instala el plugin

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

Durante la instalación se te solicitará:

• Directorio de la aplicación Tauri: ruta relativa a la raíz del proyecto (ej. . para repositorios de una sola aplicación, apps/desktop para monorepos).

2. Ejecuta el comando de instalación

/tauri-mcp:install

Esto edita automáticamente tu proyecto Tauri: Cargo.toml, src-tauri/src/lib.rs, capacidades, package.json, la entrada del frontend (main.tsx/main.ts) y .gitignore. Cada escritura se previsualiza como un diff y requiere tu confirmación primero.

3. Reinicia Claude Code

El servidor MCP tauri-mcp se registra al reiniciar. Verifica con /mcp: debería mostrar tauri-mcp como conectado. Ahora puedes llamar a start_session, snapshot, click, etc.

¿Por qué reiniciar?

Los servidores MCP se registran al iniciar Claude Code. Instalar el plugin o cambiar tauri_app_dir requiere un reinicio para que surta efecto.

Qué incluye el plugin

El servidor MCP se entrega como un paquete de un solo archivo autocontenido (packages/tauri-mcp/dist/index.js) con todas las dependencias integradas; no se necesita node_modules en la máquina de destino, por lo que la instalación funciona de forma idéntica en macOS, Linux y Windows.

Qué incluye:

Características

• Multiplataforma: Windows (Named Pipes) + macOS/Linux (Unix Sockets)

• Sin dependencia de CDP: Funciona en todos los backends de WebView, incluido macOS WKWebView

• Integración MCP: Integración directa con Claude Code y otros clientes MCP

• Soporte multiventana: Apunta a cualquier ventana por etiqueta; inyección automática de puente

• Registro unificado: Registros de compilación, tiempo de ejecución, consola y red con filtrado

• Asignación dinámica de puertos: Asignación automática de puertos aleatorios para evitar conflictos

Requisitos previos

• Node.js >= 18

• Tauri v2.x

• pnpm (recomendado) o npm

• Rust con cargo

Inicio rápido

1. [ ] Añadir plugin de Rust a src-tauri/Cargo.toml

2. [ ] Instalar paquete npm: pnpm add github:DaveDev42/tauri-plugin-mcp#main

3. [ ] Registrar plugin en src-tauri/src/lib.rs

4. [ ] Añadir permiso mcp:default

5. [ ] Inicializar puente en main.tsx

6. [ ] Crear .mcp.json para Claude Code

Instalación

1. Plugin de Rust (src-tauri/Cargo.toml)

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

2. API de Frontend (package.json)

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

3. Servidor MCP

El binario del servidor MCP (tauri-mcp) está disponible automáticamente después de la instalación. No se requiere configuración adicional.

Configuración

1. Registrar el plugin (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ñadir permisos

Opción A: En tauri.conf.json o config/*.json5 (recomendado)

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

Opción B: Archivo separado (src-tauri/capabilities/default.json)

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

3. Inicializar el puente (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);
    });
  });
}

Configuración segura para producción (Dependencia opcional)

La configuración básica anterior incluye MCP en todas las compilaciones. Para aplicaciones de producción, probablemente quieras MCP solo en desarrollo y eliminado por completo de los binarios de lanzamiento.

Este enfoque utiliza la función de dependencia opcional de Cargo para que el plugin solo se compile cuando se solicite explícitamente.

1. Dependencia opcional de Cargo (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. Registro condicional del plugin (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. División del archivo de capacidades

Separa mcp:default en su propio archivo de capacidad para que pueda activarse/desactivarse en tiempo de compilación.

capabilities/default.json — siempre activo, sin permiso MCP:

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

capabilities/.dev-tools.json.disabled — plantilla de permiso MCP (rastreada por git):

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

capabilities/dev-tools.json — añadir a .gitignore (generado en tiempo de compilación):

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

4. build.rs — gestión condicional de capacidades

build.rs copia la plantilla en su lugar cuando la función está habilitada, y la elimina en caso contrario:

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. Script de desarrollo (package.json)

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

Ahora pnpm dev habilita MCP, mientras que tauri build (sin la función) produce un lanzamiento limpio sin código MCP.

Nota: El protector del puente frontend (import.meta.env.DEV) de la configuración básica sigue aplicándose: evita que el puente se inicialice incluso si el plugin estuviera presente en tiempo de ejecución.

Configuración del servidor MCP

Nota: Si instalaste el Plugin de Claude Code, el servidor MCP ya está configurado automáticamente. El plugin solicita el directorio de la aplicación Tauri durante la instalación. Esta sección es para configuración manual sin el plugin.

Añade a .mcp.json en la raíz de tu proyecto:

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

Nota: Los usuarios de pnpm también pueden usar pnpx tauri-mcp o pnpm exec tauri-mcp.

Configuración de Monorepo

Si la aplicación Tauri está en un subdirectorio (ej. apps/desktop), establece TAURI_APP_DIR:

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

Múltiples aplicaciones Tauri

Para monorepos con múltiples aplicaciones Tauri, ejecuta una instancia de servidor MCP separada por aplicación:

{
  "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" }
    }
  }
}

Las herramientas tienen nombres de espacio por nombre de servidor: mcp__tauri-desktop__snapshot, mcp__tauri-kiosk__snapshot, etc.

Herramientas disponibles

Ciclo de vida de la sesión

Gestión de ventanas

Interacción

Todas las herramientas de interacción aceptan un parámetro opcional window para apuntar a una ventana específica (por defecto es la ventana enfocada).

Observabilidad

Uso del parámetro features

Para lanzar con características de Cargo:

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

Esto ejecuta: pnpm tauri dev --features my_feature

Ejemplo de uso

Flujo de trabajo de prueba típico:

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

Cómo funciona

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

1. Plugin de Rust crea servidor IPC (socket Unix o tubería con nombre de Windows)

2. Servidor MCP se conecta a IPC y expone herramientas a Claude

3. Puente JS (initMcpBridge()) habilita operaciones DOM en WebView

Rutas de socket

• Unix: {project_root}/.tauri-mcp.sock

• Windows: \\.\pipe\tauri-mcp-{hash} (hash derivado de la ruta del proyecto)

Solución de problemas

"MCP bridge not initialized"

El puente JS no se está ejecutando. Comprueba:

• initMcpBridge() se llama en tu código frontend

• La aplicación se está ejecutando en modo desarrollo (import.meta.env.DEV)

• Comprueba la consola del navegador para errores de inicialización

Fallo en la conexión del socket

• Asegúrate de que la aplicación se esté ejecutando (primero start_session)

• En Windows, comprueba la ruta de la tubería en los registros: [tauri-plugin-mcp] full_path: \\.\pipe\tauri-mcp-XXXXX

• En Unix, comprueba si .tauri-mcp.sock existe en la raíz del proyecto

Tiempo de espera de lanzamiento de la aplicación

• Aumenta timeout_secs (por defecto: 60)

• Comprueba si pnpm tauri dev funciona manualmente

• Busca errores de compilación en la salida de la terminal

snapshot devuelve vacío

• Espera a que la aplicación cargue completamente (usa wait_for_ready: true)

• Comprueba si el puente se inicializó (busca registros [MCP] en la consola)

Desarrollo

Después de clonar, pnpm install configura automáticamente los hooks de git y compila el proyecto.

Los directorios dist/ se confirman en el repositorio para que las instalaciones basadas en git (pnpm add github:...) funcionen sin un paso de compilación. Un hook de pre-commit verifica que dist/ se mantenga sincronizado con las fuentes de TypeScript; si el hook bloquea tu commit, ejecuta:

pnpm build
git add packages/*/dist/

Luego vuelve a intentar tu commit.

Licencia

MIT OR Apache-2.0