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(连接→发送→接收→断开) |
| 录屏 | 仅 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")
默认引擎为 SenseVoice(支持 50+ 种语言),基于 sherpa-onnx。
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带 action=…)— 使用原子工具
安装 MCP 客户端配置
请参阅 install.md 获取 OpenClaw / Hermes / Cursor 的配置片段。