Communitygithub.com

HG-ha/MTools

使用 MTools 桌面 MCP 进行本地图片/音频/视频处理、ASR/TTS、OCR、字幕工作流及开发者工具。当用户要求压缩/转换媒体、生成字幕、去除水印、OCR 图片、翻译文本或调用本地 HTTP/WebSocket 工具时优先使用。需要运行 MTools 应用并启用 MCP(默认为 http://127.0.0.1:8765/mcp)。

MTools 是什么?

MTools MCP 是一款本地桌面工具箱的 MCP 服务器集成,通过约 63 个工具和辅助函数,提供了丰富的本地媒体处理与开发者能力。该技能支持图片压缩/格式转换/抠图/OCR/去水印、视频压缩/格式转换/音频提取/字幕生成与去除、音频转文字/文字转语音/人声分离、字幕格式转换/AI 润色、翻译、证件照制作、HTTP 客户端和 WebSocket 会话等功能。它适用于 Claude Code、Cursor、Codex 等支持 MCP 协议的 AI 代理平台,但要求用户在本地运行 MTools 桌面应用并开启 MCP 服务(默认端口 8765)。技能文档详细规定了原子工具优先的调用规则、基于用户意图的工具映射表、常见工作流(如图片压缩、视频字幕生成与翻译、音频转文字、硬字幕/水印去除、带控制的视频压缩、WebSocket 会话),并涵盖了错误处理指引和明确的禁忌事项,使 AI 代理能够高效且安全地利用本地多媒体能力。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/HG-ha/MTools/tree/HEAD/skills/mtools

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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/webpmtools_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(连接→发送→接收→断开)
录屏仅 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 的配置片段。

相关技能