MTools MCP은(는) 무엇을 하나요?
MTools는 로컬 데스크톱 도구 상자입니다. 내장 MCP 서버를 통해 약 63개의 도구(및 헬퍼)를 노출합니다. 이 스킬은 언제, 어떻게 호출할지 알려줍니다.
전제 조건
- 사용자가 MTools 데스크톱 앱을 실행 중이어야 합니다.
- 설정 → MCP 服务 → 활성화되어 있어야 합니다.
- 기본 엔드포인트:
http://127.0.0.1:8765/mcp - AI/ONNX 기능은 MTools GUI 내에서 모델을 이미 다운로드해야 합니다.
MCP가 오프라인이면: 사용자에게 MTools를 열고 MCP를 활성화하라고 알리세요. 경로를 임의로 만들지 마세요.
호출 규칙 (엄격)
- 원자적 도구를 선호하세요:
mtools_image_compress,mtools_video_convert, ... - 알 수 없는 매개변수 → 먼저
mtools_help("image.compress")호출 - 기능 목록 →
mtools_tool_ids()또는mtools_help()호출 - 대체 진입점 →
mtools_run(tool_id, params_json)호출 - 경로는 사용자 머신의 절대 로컬 경로여야 합니다.
- 응답은 JSON 문자열입니다 — 계속 진행하기 전에
ok확인 - 마크다운 뷰어는 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 |
| WebSocket | mtools_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_imagewith action=…)를 호출하지 마세요 — 원자적 도구를 사용하세요.
MCP 클라이언트 구성 설치
OpenClaw / Hermes / Cursor 스니펫은 install.md를 참조하세요.