tauri-plugin-mcp

MCP (Model Context Protocol)를 통한 크로스 플랫폼 Tauri 테스트 자동화 플러그인.

Claude와 같은 AI 어시스턴트가 테스트 및 자동화를 위해 Tauri 데스크탑 앱과 상호작용할 수 있도록 합니다.

Claude Code 플러그인

이 저장소는 Claude Code 플러그인으로도 작동합니다. 완벽하게 작동하는 설정을 위한 세 단계:

1. 마켓플레이스 추가 및 플러그인 설치

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

설치 중에 다음 항목을 묻는 메시지가 표시됩니다:

• Tauri 앱 디렉토리: 프로젝트 루트 기준 경로 (예: 단일 앱 저장소의 경우 ., 모노레포의 경우 apps/desktop).

2. 설치 프로그램 명령 실행

/tauri-mcp:install

이 명령은 Tauri 프로젝트(Cargo.toml, src-tauri/src/lib.rs, capabilities, package.json, 프론트엔드 엔트리(main.tsx/main.ts), .gitignore)를 자동으로 편집합니다. 모든 쓰기 작업은 먼저 diff로 미리보기되며 사용자의 확인이 필요합니다.

3. Claude Code 재시작

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에서 동일하게 설치됩니다.

포함된 내용:

기능

• 크로스 플랫폼: Windows (Named Pipes) + macOS/Linux (Unix Sockets)

• CDP 의존성 없음: macOS WKWebView를 포함한 모든 WebView 백엔드에서 작동

• MCP 통합: Claude Code 및 기타 MCP 클라이언트와 직접 통합

• 다중 창 지원: 레이블별로 창 타겟팅; 자동 브리지 주입

• 통합 로깅: 필터링 기능이 포함된 빌드, 런타임, 콘솔 및 네트워크 로그

• 동적 포트 할당: 충돌 방지를 위한 자동 무작위 포트 할당

사전 요구 사항

• Node.js >= 18

• Tauri v2.x

• pnpm (권장) 또는 npm

• Rust (cargo 포함)

빠른 시작

1. [ ] src-tauri/Cargo.toml에 Rust 플러그인 추가

2. [ ] npm 패키지 설치: pnpm add github:DaveDev42/tauri-plugin-mcp#main

3. [ ] src-tauri/src/lib.rs에 플러그인 등록

4. [ ] mcp:default 권한 추가

5. [ ] main.tsx에서 브리지 초기화

6. [ ] Claude Code를 위한 .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/*.json5 (권장)

{
  "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. 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. 조건부 플러그인 등록 (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. Capabilities 파일 분할

mcp:default를 별도의 capability 파일로 분리하여 빌드 시점에 토글할 수 있도록 합니다.

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 — 조건부 capabilities 관리

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 Code 플러그인을 설치했다면 MCP 서버는 이미 자동으로 구성되었습니다. 플러그인은 설치 중에 Tauri 앱 디렉토리를 묻습니다. 이 섹션은 플러그인 없이 수동으로 설정하는 경우를 위한 것입니다.

프로젝트 루트의 .mcp.json에 추가하세요:

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

참고: pnpm 사용자는 pnpx tauri-mcp 또는 pnpm exec tauri-mcp를 사용할 수도 있습니다.

모노레포 구성

Tauri 앱이 하위 디렉토리(예: apps/desktop)에 있는 경우 TAURI_APP_DIR을 설정하세요:

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

다중 Tauri 앱

여러 Tauri 앱이 있는 모노레포의 경우, 앱당 별도의 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 등.

사용 가능한 도구

세션 수명 주기

창 관리

상호작용

모든 상호작용 도구는 특정 창을 타겟팅하기 위한 선택적 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

1. Rust 플러그인이 IPC 서버(Unix 소켓 또는 Windows 명명된 파이프) 생성

2. MCP 서버가 IPC에 연결하고 Claude에 도구 노출

3. JS 브리지(initMcpBridge())가 웹뷰에서 DOM 작업 활성화

소켓 경로

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

• Windows: \\.\pipe\tauri-mcp-{hash} (해시는 프로젝트 경로에서 파생됨)

문제 해결

"MCP bridge not initialized"

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가 수동으로 작동하는지 확인

• 터미널 출력에서 빌드 오류 확인

snapshot이 비어 있음

• 앱이 완전히 로드될 때까지 대기 (wait_for_ready: true 사용)

• 브리지가 초기화되었는지 확인 (콘솔에서 [MCP] 로그 확인)

개발

복제 후 pnpm install은 자동으로 git 훅을 구성하고 프로젝트를 빌드합니다.

dist/ 디렉토리는 저장소에 커밋되므로 git 기반 설치(pnpm add github:...)가 빌드 단계 없이 작동합니다. 사전 커밋 훅은 dist/가 TypeScript 소스와 동기화 상태를 유지하는지 확인합니다. 훅이 커밋을 차단하면 다음을 실행하세요:

pnpm build
git add packages/*/dist/

그런 다음 커밋을 다시 시도하세요.

라이선스

MIT OR Apache-2.0