Communitygithub.com

MTools MCP

MTools 데스크톱 MCP를 활용하여 로컬 이미지/오디오/비디오 처리, ASR/TTS, OCR, 자막 워크플로우 및 개발자 유틸리티를 사용합니다.

MTools MCP란 무엇인가요?

MTools MCP 스킬은 로컬 데스크톱 도구 상자인 MTools의 내장 MCP 서버를 통해 63개 이상의 도구를 AI 어시스턴트에서 호출할 수 있게 해줍니다. 이미지 압축/변환/배경 제거, 동영상 압축/변환/자막 생성/워터마크 제거, 오디오 텍스트 변환(STT/TTS), OCR, 자막 변환/보정, HTTP/WebSocket 요청 등 다양한 작업을 로컬에서 실행합니다. Claude Code, Cursor, Codex와 같은 AI 에이전트에서 MCP 프로토콜을 통해 도구를 호출하며, 사용자가 로컬 파일 처리를 요청할 때 유용합니다. MTools 데스크톱 앱이 실행 중이어야 하며, MCP 서비스가 활성화되어 있어야 합니다. 각 도구는 'mtools_' 접두사를 가진 원자적 함수로 제공되며, 자동 오디오/비디오 처리, 자막 워크플로우, 개발 디버깅 도구 등 다양한 작업을 효율적으로 처리할 수 있습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/HG-ha/MTools/tree/HEAD/skills/mtools

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

MTools MCP은(는) 무엇을 하나요?

MTools는 로컬 데스크톱 도구 상자입니다. 내장 MCP 서버를 통해 약 63개의 도구(및 헬퍼)를 노출합니다. 이 스킬은 언제, 어떻게 호출할지 알려줍니다.

전제 조건

  1. 사용자가 MTools 데스크톱 앱을 실행 중이어야 합니다.
  2. 설정 → MCP 服务 → 활성화되어 있어야 합니다.
  3. 기본 엔드포인트: http://127.0.0.1:8765/mcp
  4. AI/ONNX 기능은 MTools GUI 내에서 모델을 이미 다운로드해야 합니다.

MCP가 오프라인이면: 사용자에게 MTools를 열고 MCP를 활성화하라고 알리세요. 경로를 임의로 만들지 마세요.

호출 규칙 (엄격)

  1. 원자적 도구를 선호하세요: mtools_image_compress, mtools_video_convert, ...
  2. 알 수 없는 매개변수 → 먼저 mtools_help("image.compress") 호출
  3. 기능 목록 → mtools_tool_ids() 또는 mtools_help() 호출
  4. 대체 진입점 → mtools_run(tool_id, params_json) 호출
  5. 경로는 사용자 머신의 절대 로컬 경로여야 합니다.
  6. 응답은 JSON 문자열입니다 — 계속 진행하기 전에 ok 확인
  7. 마크다운 뷰어는 MCP를 통해 노출되지 않습니다.

빠른 맵 (사용자 의도 → 도구)

사용자 말호출
이미지 압축mtools_image_compress
이미지를 jpg/png/webp로 변환mtools_image_format
누끼 / 배경 제거mtools_image_background
OCR / 텍스트 인식mtools_image_ocr
이미지 워터마크 제거mtools_image_watermark_remove
비디오 압축mtools_video_compress
비디오 형식 변환mtools_video_convert
비디오에서 오디오 추출mtools_video_extract_audio
비디오 자막 제거mtools_video_subtitle_remove
비디오 자막 생성mtools_video_subtitle ( target_lang/bilingual/burn_in 가능)
TS 분할 병합mtools_video_ts_merge
오디오를 텍스트로 변환mtools_audio_to_text
텍스트를 음성으로 변환mtools_audio_text_to_speech
보컬 분리mtools_audio_vocal_extraction / mtools_video_vocal_separation
자막 형식 변환mtools_subtitle_convert
AI 자막 보정mtools_ai_subtitle_fix
번역mtools_others_translate
증명사진mtools_others_id_photo
HTTP 요청mtools_dev_http_client
WebSocketmtools_websocket (connect→send→receive→disconnect)
화면 녹화GUI 전용, MCP 사용 불가

명명 규칙: tool_id image.compress → 원자적 도구 mtools_image_compress (mtools_ + 점 → 밑줄).

워크플로우

A. 사진 압축

mtools_image_compress(
  input_path="C:/photos/a.jpg",
  quality="high",          # high|medium|low
  compress_mode_name="balanced"  # fast|balanced|max
)

B. 비디오 → 자막 (타임스탬프 / 번역 / 영상 내장)

mtools_video_subtitle(
  input_path="C:/a.mp4",
  language="zh",
  target_lang="en",   # 선택적 번역
  bilingual=True,     # 원본 + 번역
  burn_in=False       # True = 영상에 내장
)

그런 다음 AI 보정으로 타이밍을 유지할 수도 있습니다:

mtools_ai_subtitle_fix(
  segments_json='[{"text":"...","start":0,"end":1.2}, ...]',
  base_url=..., api_key=..., model=...
)

먼저 MTools에 SenseVoice/Whisper 모델이 다운로드되어 있어야 합니다.

C. 오디오 → 텍스트

mtools_audio_to_text(input_path="C:/a.mp3", language="zh")

기본 엔진은 sherpa-onnx를 통한 SenseVoice(50개 이상 언어)입니다.

D. 하드 자막 / 워터마크 제거

정확한 영역을 선호:

mtools_video_subtitle_remove(
  input_path="C:/a.mp4",
  left=0, top=800, right=1920, bottom=1080
)

또는 밴드: subtitle_region="bottom"|"top". MTools에 자막 제거 모델이 필요합니다.

E. 제어로 비디오 압축

mtools_video_compress(input_path="C:/a.mp4", scale="720p", crf=23, fps=30)

F. WebSocket 세션

1. mtools_websocket(action="connect", url="ws://127.0.0.1:8080")
   → session_id 저장
2. mtools_websocket(action="send", session_id=..., message="ping")
3. mtools_websocket(action="receive", session_id=...)
4. mtools_websocket(action="disconnect", session_id=...)

오류 처리

증상조치
연결 거부사용자에게 MTools 시작 + MCP 활성화 요청
ok: false + 모델 미다운로드사용자에게 MTools GUI에서 모델 다운로드 요청
경로 없음실제 절대 경로 요청
ffmpeg 사용 불가사용자에게 MTools 설정에서 FFmpeg 구성 요청

해야 할 것 / 하지 말아야 할 것

  • 해야 할 것: MCP가 정상인지 확실하지 않으면 mtools_status를 한 번 호출하세요.
  • 해야 할 것: 자동 출력으로 충분하면 output_path를 비워 두세요.
  • 하지 말아야 할 것: mtools_ai_subtitle_fix의 API 키를 노출하거나 기록하지 마세요.
  • 하지 말아야 할 것: 화면 녹화가 MCP에서 작동한다고 주장하지 마세요.
  • 하지 말아야 할 것: 레거시 도구(mtools_image with action=…)를 호출하지 마세요 — 원자적 도구를 사용하세요.

MCP 클라이언트 구성 설치

OpenClaw / Hermes / Cursor 스니펫은 install.md를 참조하세요.

관련 스킬