위챗 미니 프로그램 MCP 서버

FastMCP 기반의 서버로, miniprogram-automator를 통해 위챗 개발자 도구를 자동화합니다. 이 서버는 AI 어시스턴트가 미니 프로그램 페이지를 탐색, 검사 및 조작할 수 있도록 MCP 도구를 제공합니다. playwright-mcp와 유사하지만 위챗 생태계에 맞게 최적화되었습니다.

사전 요구 사항

• 명령줄 액세스(cli / cli.bat)를 지원하는 위챗 개발자 도구가 설치되어 있어야 합니다.

• 로컬에 Node.js 18+ 및 npm이 설치되어 있어야 합니다.

• 개발자 도구에서 열 수 있는 미니 프로그램 프로젝트가 있어야 합니다.

빠른 시작 (npm 패키지)

@yfme/weapp-dev-mcp는 npm에 배포되어 있으므로, 일반 사용자는 저장소를 복제하거나 node dist/index.js를 수동으로 실행할 필요가 없습니다.

npx로 실행

npx -y @yfme/weapp-dev-mcp

프로젝트/전역 설치

npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp

또는 프로젝트 의존성으로 추가:

npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp

본 저장소 내에서 개발하는 경우에만 node dist/index.js를 직접 실행하는 것을 권장합니다. 일반 사용자는 위의 npm 패키지 방식으로 시작하십시오.

MCP 클라이언트 통합

설정

Claude Desktop 또는 기타 MCP 클라이언트에서 이 서버를 사용하려면 설정 파일에 다음을 추가하십시오:

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@yfme/weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

Claude Code 자동 도구 권한 승인

Claude Code를 사용하여 MCP 도구를 호출할 때 도구 호출 권한 승인 요청이 발생하면, MCP와 위챗 개발자 도구 간의 연결 상태가 끊길 수 있습니다. 콘솔 출력은 연결 상태에 크게 의존하므로 로그를 연속적으로 가져올 수 없게 됩니다. 따라서 권한을 수동으로 추가하는 것을 권장합니다:

프로젝트 디렉토리에 .claude/settings.local.json 파일을 생성하거나 기존 파일에 다음 내용을 추가하면 확인 절차 없이 도구를 직접 호출할 수 있습니다. 필요에 따라 승인할 도구를 추가하십시오:

{
  "permissions": {
    "allow": [
      "mcp__weapp-dev-mcp__mp_ensureConnection",
      "mcp__weapp-dev-mcp__mp_navigate",
      "mcp__weapp-dev-mcp__mp_screenshot",
      "mcp__weapp-dev-mcp__mp_callWx",
      "mcp__weapp-dev-mcp__mp_getLogs",
      "mcp__weapp-dev-mcp__mp_currentPage",
      "mcp__weapp-dev-mcp__mp_listProjects",
      "mcp__weapp-dev-mcp__mp_setDefaultProject",
      "mcp__weapp-dev-mcp__page_getElement",
      "mcp__weapp-dev-mcp__page_getElements",
      "mcp__weapp-dev-mcp__page_waitElement",
      "mcp__weapp-dev-mcp__page_waitTimeout",
      "mcp__weapp-dev-mcp__page_getData",
      "mcp__weapp-dev-mcp__page_setData",
      "mcp__weapp-dev-mcp__page_callMethod",
      "mcp__weapp-dev-mcp__element_tap",
      "mcp__weapp-dev-mcp__element_input",
      "mcp__weapp-dev-mcp__element_callMethod",
      "mcp__weapp-dev-mcp__element_getData",
      "mcp__weapp-dev-mcp__element_setData",
      "mcp__weapp-dev-mcp__element_getInnerElement",
      "mcp__weapp-dev-mcp__element_getInnerElements",
      "mcp__weapp-dev-mcp__element_getWxml",
      "mcp__weapp-dev-mcp__element_getStyles",
      "mcp__weapp-dev-mcp__element_scrollTo",
      "mcp__weapp-dev-mcp__element_getAttributes",
      "mcp__weapp-dev-mcp__element_getBoundingClientRect"
    ]
  }
}

주의: 도구 이름 형식은 mcp__<서버 이름>__<도구 이름>입니다. 서버 이름이 MCP 설정의 이름과 일치하는지 확인하십시오.

위챗 개발자 도구 시작

MCP 서버를 사용하기 전에 위챗 개발자 도구를 시작하고 WebSocket 서비스를 활성화해야 합니다.

💡 시작하기 전에:

1. 위챗 개발자 도구를 엽니다.

2. **설정(Settings) → 보안 설정(Security Settings) → 서비스 포트(Service Port)**로 이동합니다.

3. **"HTTP 디버깅(HTTP Debugging)"**과 **"자동화 테스트(Automation Test)"**를 켭니다.

명령줄을 사용하여 시작

명령줄을 사용하여 위챗 개발자 도구를 시작하고 WebSocket 서비스를 자동으로 활성화합니다:

macOS/Linux:

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows:

"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420

설명:

• --project 매개변수는 미니 프로그램 프로젝트 디렉토리 경로를 지정합니다 (실제 경로로 교체하십시오).

• --auto-port 매개변수는 WebSocket 서비스 포트를 지정합니다 (기본값 9420).

⚠️ 경고 샌드박스 메커니즘으로 인해 일부 클라이언트는 MCP가 프로젝트 디렉토리 외부의 위챗 개발자 도구 CLI에 액세스하는 것을 허용하지 않으므로, 여기서는 WebSocket 서비스를 사용하는 방법만 설명합니다.

환경 변수 설정

환경 변수를 통해 자동화 도구가 위챗 개발자 도구에 연결되는 방식을 제어합니다:

주의: 개발자 도구를 시작(launch 모드)할 때, MCP 도구 매개변수를 통해 미니 프로그램 프로젝트 디렉토리를 제공해야 합니다. 작업 수행 전 connection.projectPath를 통해 제공하십시오 (예: mp_ensureConnection). 이 값은 설정되면 후속 호출에서 유지됩니다.

도구 호출은 connection 객체를 통해 이러한 기본값 대부분을 덮어쓸 수 있습니다.

사용 가능한 도구

애플리케이션 도구 (Application Tools)

• mp_ensureConnection – 자동화 세션 준비 확인; 강제 재연결 또는 연결 설정 덮어쓰기 가능

• mp_navigate – 미니 프로그램 내 탐색 (navigateTo, redirectTo, reLaunch, switchTab, navigateBack 지원)

• mp_screenshot – 스크린샷 캡처 및 반환 (또는 디스크에 저장)

• mp_callWx – 위챗 미니 프로그램 API 메서드 호출 (예: wx.showToast)

• mp_getLogs – 미니 프로그램 콘솔 로그 가져오기, 가져온 후 삭제 옵션 제공

• mp_currentPage – 현재 페이지 정보 가져오기 (경로, 쿼리 매개변수, 크기, 스크롤 위치), withData가 true일 경우 페이지 데이터 추가 반환

• mp_listProjects – 위챗 개발자 도구의 최근 프로젝트 목록 표시 (프로젝트 디렉토리 선택 용이)

• mp_setDefaultProject – 기본 미니 프로그램 프로젝트 경로 설정, 설정 후 다음 연결 시 자동으로 해당 프로젝트 사용

페이지 도구 (Page Tools)

• page_getElement – 선택자를 통해 페이지 요소 가져오기, 요소 요약 정보 반환 (tagName, text, value, size, offset); withWxml: true 설정 시 전체 outerWxml 추가 반환; [index=N] 구문을 사용하여 N번째 요소 선택 지원

• page_getElements – 선택자를 통해 페이지 요소 배열 가져오기, 각 요소의 요약 정보 반환; withWxml: true 설정 시 각 요소의 전체 outerWxml 추가 반환; [index=N] 구문 지원

• page_waitElement – 페이지에 요소가 나타날 때까지 대기 (⚠️ 사용자 정의 컴포넌트 내부 요소에는 적용 불가); [index=N] 구문 지원; 시간 초과 및 재시도 간격 매개변수 추가

• page_waitTimeout – 지정된 밀리초만큼 대기

• page_getData – 현재 페이지의 데이터 객체 가져오기, 경로 지정 가능 ('user.name'과 같은 중첩 경로 지원)

• page_setData – setData를 사용하여 현재 페이지 데이터 업데이트; 데이터가 실제로 업데이트되었는지 확인하는 verify 옵션 추가

• page_callMethod – 현재 페이지 인스턴스에 노출된 메서드 호출

요소 도구 (Element Tools)

• element_tap – CSS 선택자를 통해 WXML 요소 클릭 시뮬레이션; [index=N] 구문으로 N번째 요소 선택 지원; x/y 좌표 오프셋 클릭 지원; 안정성 강화: 요소 상호작용 가능 상태 대기, 클릭 후 페이지 경로 변경 자동 확인

• element_input – 요소에 텍스트 입력 (input 및 textarea 컴포넌트에 적용)

• element_callMethod – 사용자 정의 컴포넌트 인스턴스의 메서드 호출

• element_getData – 사용자 정의 컴포넌트 인스턴스의 렌더링 데이터 가져오기

• element_setData – 사용자 정의 컴포넌트 인스턴스의 렌더링 데이터 설정

• element_getInnerElement – 요소 내부의 요소 가져오기 (element.$(selector)와 동일), 요소 요약 정보 반환; withWxml: true 설정 시 전체 outerWxml 추가 반환

• element_getInnerElements – 요소 내부의 요소 배열 가져오기 (element.$$(selector)와 동일), 요소 요약 정보 반환; withWxml: true 설정 시 각 요소의 전체 outerWxml 추가 반환

• element_getWxml – 요소 WXML 가져오기 (내부 또는 외부)

• element_getStyles – 요소의 CSS 스타일 값 가져오기, names 매개변수는 스타일 이름 배열 (예: ['color', 'fontSize'])

• element_scrollTo – scroll-view 컴포넌트를 지정된 위치(x, y)로 스크롤

• element_getAttributes – 요소의 속성 값 가져오기, names 매개변수는 속성 이름 배열 (예: ['class', 'id', 'data-index'])

• element_getBoundingClientRect – 뷰포트 기준 요소의 경계 사각형 정보(left, top, width, height, right, bottom) 가져오기, CSS transform 변환 고려 (현재 ID 선택자, 클래스 선택자만 지원)

각 도구는 환경 기본값(프로젝트 경로, CLI 경로, WebSocket 엔드포인트 등)을 덮어쓰기 위한 선택적 connection 블록을 허용합니다.

사용 팁

일반 팁

• 연결 전 위챗 개발자 도구에서 자동화 활성화 (설정 → 보안 설정 → 서비스 포트)

• 먼저 mp_ensureConnection을 호출하여 연결을 확인하고 시스템/페이지 세부 정보를 확인하는 것을 권장합니다.

• WEAPP_AUTOCLOSE=true는 상태가 없는 일회성 상호작용에 적합합니다.

• 탐색 시 항상 절대 경로를 사용하십시오 ( /로 시작): /pages/mine/mine

• tabBar 페이지는 switchTab을, 일반 페이지는 navigateTo를 사용하십시오.

사용자 정의 컴포넌트 조작

사용자 정의 컴포넌트를 조작할 때는 두 가지 방법이 있습니다:

방법 1: innerSelector 매개변수 사용 (권장)

element_tap, element_input, element_getWxml 등의 도구에 적용 가능:

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector: 사용자 정의 컴포넌트의 선택자

• innerSelector: 컴포넌트 내부 요소의 선택자

방법 2: 요소 내부 쿼리 도구 사용

element_getInnerElement 및 element_getInnerElements 도구에 적용 가능:

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

제한 사항

• page_waitElement는 사용자 정의 컴포넌트 내부 요소에 적용되지 않습니다. page_waitTimeout과 요소 쿼리 도구를 함께 사용하여 폴링(polling) 방식으로 확인하십시오.

자동 시작 기능 (AutoLaunch)

WEAPP_AUTOLAUNCH=true로 설정하면 MCP 서버가 위챗 개발자 도구를 자동으로 감지하고 시작할 수 있습니다:

1. 포트 자동 감지: 9420 포트에서 서비스가 실행 중인지 확인

2. 서비스 미실행 시 시작: 포트가 사용 중이 아니면 CLI를 호출하여 개발자 도구 시작

3. 프로젝트 선택:

   • 기본 프로젝트 설정이 있으면 자동으로 사용

   • 기본 프로젝트가 없으면 최근 프로젝트 목록을 표시하여 선택 유도

   • 프로젝트 번호(예: 1) 또는 전체 경로 입력 지원

설정 예시

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": ["-y", "weapp-dev-mcp"],
      "env": {
        "WEAPP_AUTOLAUNCH": "true",
        "WEAPP_PROJECT_PATH": "D:\\path\\to\\your\\project"
      }
    }
  }
}

워크플로우

1. 최초 연결 시 WEAPP_AUTOLAUNCH=true 감지

2. 9420 포트에서 서비스 실행 여부 확인

3. 서비스가 없으면 개발자 도구 자동 시작 (cli.bat auto --project <path> --auto-port 9420 사용)

4. 개발자 도구가 준비될 때까지 45초 대기

5. WebSocket 연결 수립

6. 후속 연결 시 기존 연결 자동 재사용

팁: mp_setDefaultProject를 사용하여 기본 프로젝트를 설정하면 다음 연결 시 프로젝트를 다시 선택할 필요가 없습니다.