Lathe

Lathe

由 Seaynic Labs 制作。 我们围绕企业自己的系统构建这类工具。查看定制集成。

Lathe 是一套面向所有需要处理文件和媒体的人的 MCP 工具包。它为你的 AI 助手提供用于处理图像、PDF、音频、视频和 OCR 的本地工具，还支持批量处理和移除元数据。文件始终保留在你的设备上。

它是一套工具包：由多个模块组成的单个服务，每个模块都可以启用或关闭。更新中新增且默认关闭的模块会保持关闭，直到你手动启用。

安全信息
网络	无。Lathe 不建立任何网络连接，并且 ffmpeg 和 ffprobe 仅限访问本地文件（-protocol_whitelist file,pipe）。只有在以这种方式启动时，--transport http 才会监听 127.0.0.1。
文件	仅在工作文件夹（LATHE_WORKING_DIR）中读取和写入文件。读取可选配置文件（/.config/lathe/config.toml）。写入一份本地审批日志（/.local/state/lathe/approvals.jsonl）。
密钥	不需要密钥、账号或密码。无需存储任何内容，也不会有任何内容离开设备。
只读工具	8 个：image_info、pdf_info、pdf_extract_text、audio_info、video_info、ocr_image、health、lathe_modules
写入新文件	audio_convert、batch_process、image_convert、image_crop、image_optimize、image_resize、image_thumbnail、pdf_compress、pdf_merge、pdf_split、pdf_to_images、scrub_metadata、video_thumbnail、video_to_gif、video_trim：每次调用都会在工作文件夹中写入新文件，除非调用传入 overwrite=true，否则绝不会覆盖已有文件。batch_process 在一次处理两个或更多文件时会询问一次，其他工具均不会询问。
启动开销	默认安装约需 7,600 个 token（21 个工具、4 个技能提示词）
变更	工具描述通过哈希锁定（tool-manifest.lock.json）；如果描述被悄悄更改，CI 将失败。

模块

模块	功能	默认开启	依赖项
images	查看信息、调整大小、转换、优化、裁剪、生成缩略图	是	Pillow（始终已安装）
pdf	查看信息、提取文本（扫描页面使用 OCR）、合并、渲染页面、拆分、压缩	是	pdf extra；渲染需要 ghostscript
media	查看音频和视频信息、转换音频、提取帧、剪辑、制作 GIF	是	ffmpeg 和 ffprobe
ocr	从图像中提取文本	是	ocr extra；tesseract
batch	对匹配 glob 的每个文件执行一次操作，先进行试运行	否	视操作而定（见上文）
privacy	检查并移除 GPS、相机和作者元数据	否	PDF 文件需要 pdf extra

Lathe 免费且采用 MIT 许可。默认提供 21 个工具，启用 batch 和 privacy 后提供 23 个。

技能

技能说明如何做好一项工作。你的 AI 助手会将其作为 Agent Skills 读取，也可以在任何 MCP 应用中将其作为 MCP 提示词读取。

技能	用途
getting-started	设置、每个缺失组件的安装命令、--doctor 和审批规则
pdf	使用 Chrome 或 Chromium 将 Markdown 文件转换为 PDF
pdf-forms	创建带有可填写文本框和复选框的 PDF
web-image-prep	移除位置数据，并缩小文件夹中的照片以供网站使用

前五分钟

1. 安装：uvx --from "lathe-mcp[pdf,ocr]" lathe --version 会打印版本号。需要 Python 3.11 或更高版本，以及 uv。
2. 将 Lathe 添加到你的客户端（见将其添加到 MCP 客户端）。将 LATHE_WORKING_DIR 设为包含文件的文件夹。
3. 运行 lathe --doctor（uvx --from "lathe-mcp[pdf,ocr]" lathe --doctor）。它会为每个组件打印 ok 或 FIX，并显示修复问题的命令。
4. 让你的助手调用 lathe_modules。它会列出所有模块、各模块的启用状态以及缺少的组件。

试试这些

设置 LATHE_WORKING_DIR 后，将以下内容粘贴到你的助手中：

1. Call lathe_modules and tell me which pieces are missing.
2. Show me the metadata in photos/trip.jpg, then make a copy without it as photos/trip-clean.jpg.（需要 LATHE_PRIVACY_ENABLED=true）
3. Dry-run image_optimize on everything in photos/ into web/, then run it.（需要 LATHE_BATCH_ENABLED=true）
4. Split report.pdf into parts of 5 pages in parts/.
5. Cut the first 10 seconds of clip.mp4 into clip-10s.mp4, then make a 5-second GIF from it.

安装

Lathe 需要 Python 3.11 或更高版本。使用 uv 时，无需预先安装任何东西。根据你要使用的模块选择额外依赖：

uvx --from lathe-mcp lathe --version                  # images, media and batch
uvx --from "lathe-mcp[pdf,ocr]" lathe --version       # with PDF and OCR

固定到此版本，以便重复配置：

uvx --from "lathe-mcp[pdf,ocr]==0.4.1" lathe --version

也可以使用 pip：

pip install "lathe-mcp[pdf,ocr]"

额外依赖：pdf（pypdf）、ocr（pytesseract）、full（两者）。images 模块无需额外依赖。

Claude Code 插件

该仓库也是一个 Claude Code 插件。其 .mcp.json 固定使用 lathe-mcp[pdf,ocr]==0.4.1，并附带 skills/ 中的技能。插件是一种安装方式；以下 MCP 配置适用于任何客户端。

系统程序

Lathe 启动时不需要这些程序。lathe --doctor 命令和 lathe_modules 工具会列出缺少的程序以及适用于你平台的安装命令。

程序	用途	macOS	Debian / Ubuntu
ffmpeg（包含 ffprobe）	media、batch（音频）	brew install ffmpeg	sudo apt install ffmpeg
tesseract	ocr，以及用于扫描页面的 pdf_extract_text	brew install tesseract	sudo apt install tesseract-ocr
ghostscript	pdf_to_images、batch（PDF）	brew install ghostscript	sudo apt install ghostscript

设置

在 MCP 客户端的配置中将这些设为环境变量，或写入配置文件。Lathe 启动时不需要设置其中任何一项。

变量	说明
LATHE_WORKING_DIR	Lathe 读取和写入文件的文件夹。默认值：服务启动时所在的文件夹。
LATHE_MAX_FILE_MB	输入文件大小上限，单位为 MB。默认值为 500。
LATHE_OCR_LANG	Tesseract 语言代码，可为多个，例如 eng 或 eng+fra。默认值为 eng。
LATHE_<MODULE>_ENABLED	true 或 false。images、pdf、media 和 ocr 默认值为 true；batch 和 privacy 默认值为 false。
LATHE_BATCH_PREAPPROVED	设为 true 后，两个或更多文件的批处理任务无需批准提示即可运行。默认值为 false。仅当你的客户端无法显示批准提示时才设置此项。
LATHE_APPROVAL_LOG	批准日志的写入位置。默认值为 ~/.local/state/lathe/approvals.jsonl。

配置文件（可选）。 Lathe 还会读取 ~/.config/lathe/config.toml，或由 LATHE_CONFIG 指定的文件。环境变量的优先级高于文件中的设置。

[core]
working_dir = "/Users/you/Pictures"

[ocr]
lang = "eng"

[batch]
enabled = true

[privacy]
enabled = true

添加到 MCP 客户端

以下客户端均通过 stdio 将 Lathe 作为本地进程运行。仅在需要的地方填写 env 值。

Claude Desktop：claude_desktop_config.json（Settings、Developer、Edit Config）

{
  "mcpServers": {
    "lathe": {
      "command": "uvx",
      "args": ["--from", "lathe-mcp[pdf,ocr]", "lathe"],
      "env": { "LATHE_WORKING_DIR": "/path/to/your/files", "LATHE_BATCH_ENABLED": "true", "LATHE_PRIVACY_ENABLED": "true" }
    }
  }
}

Claude Code

claude mcp add lathe -e LATHE_WORKING_DIR=/path/to/your/files -- uvx --from "lathe-mcp[pdf,ocr]" lathe

Cursor：~/.cursor/mcp.json，或项目中的 .cursor/mcp.json

{
  "mcpServers": {
    "lathe": {
      "command": "uvx",
      "args": ["--from", "lathe-mcp[pdf,ocr]", "lathe"],
      "env": { "LATHE_WORKING_DIR": "/path/to/your/files" }
    }
  }
}

VS Code：.vscode/mcp.json（注意使用 "servers"，而非 "mcpServers"）

{
  "servers": {
    "lathe": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "lathe-mcp[pdf,ocr]", "lathe"],
      "env": { "LATHE_WORKING_DIR": "/path/to/your/files" }
    }
  }
}

Sonique、Hermes、OpenClaw 及其他客户端：任何能够启动 stdio MCP 服务的客户端。命令为 uvx，参数为 ["--from", "lathe-mcp[pdf,ocr]", "lathe"]，并加上上述 env 值。

通过 HTTP 连接。 对于通过 URL 连接而非启动进程的客户端：

lathe --transport http --port 8765

服务在 http://127.0.0.1:8765/mcp 提供可流式传输的 HTTP 接口。默认情况下仅监听本机。在其他任何地方公开此接口之前，请先配置身份验证。

工具

工具	模块	功能	是否会先询问
health	core	服务器版本、工作文件夹，以及各外部程序是否已安装	否
lathe_modules	core	已启用的模块、缺少的内容（附安装命令）、技能，以及各工具所需的内容	否
image_info	images	宽度、高度、格式、模式、大小和 EXIF 标签	否
image_resize	images	按宽度、高度或百分比调整大小，并保持宽高比	否
image_convert	images	转换为 png、jpeg、webp、avif 或 bmp	否
image_optimize	images	缩小文件以便在网络上传输；除非设为 strip_metadata=false，否则会剥除元数据	否
image_crop	images	裁剪矩形区域	否
image_thumbnail	images	将图像缩放至适合正方形	否
pdf_info	pdf	页数、大小、加密状态、标题、作者	否
pdf_extract_text	pdf	提取指定页面或整个文件的文本；对没有文本层的页面进行 OCR；长文本分段返回	否
pdf_merge	pdf	按顺序合并 PDF	否
pdf_to_images	pdf	按指定 DPI 将页面渲染为 PNG 或 JPEG	否
pdf_split	pdf	按每 N 页拆分为多个部分	否
pdf_compress	pdf	无损生成更小的副本：压缩内容流并移除重复对象	否
audio_info	media	时长、格式、比特率、采样率、声道数	否
audio_convert	media	转换为 mp3、wav、flac、aac 或 ogg	否
video_info	media	时长、分辨率、编解码器、帧率、音轨	否
video_thumbnail	media	将指定秒数处的一帧保存为图像	否
video_trim	media	剪切一段视频（流复制；剪切点落在关键帧上）	否
video_to_gif	media	将最长 30 秒的视频转换为动画 GIF	否
ocr_image	ocr	提取图像中的文本；长文本分段返回	否
batch_process	batch	对每个匹配文件执行一项操作；默认先试运行	是，处理 2 个或更多文件时
scrub_metadata	privacy	检查（默认），或生成不含 GPS、相机或作者元数据的副本	否

每个工具都会返回符合已发布架构的结构化数据。长文本会分段返回：将 next_offset 作为 offset 传回。错误始终采用以下格式：lathe.<module>.<code>: <message> Fix: <hint>。

审批

只有 batch_process 会询问，并且仅在处理 2 个或更多文件时询问。客户端会向用户展示一份计划，其中包括操作、输出文件夹、是否可能替换已有输出、文件数量，以及最多 10 个文件名。用户只需针对整个批次批准或拒绝一次。模型不能代替用户作答。无法显示提示词的客户端会收到 approval_unavailable，以及用于修复问题的设置（LATHE_BATCH_PREAPPROVED=true）。

其他所有写入工具每次调用都会写入一个新文件，无需询问。除非调用时传入 overwrite=true，否则这些工具都不会覆盖已有文件。

文件与安全

• 工作文件夹。 相对路径以 LATHE_WORKING_DIR 为基准解析。输入和输出必须位于该文件夹内。指向文件夹外部的符号链接会被拒绝。
• 不会意外覆盖文件。 除非调用时传入 overwrite=true，否则已有输出会被拒绝。输出永远不能是输入文件。
• 批量处理不会触碰输入文件。 batch_process 会拒绝将输入文件夹设为输出文件夹，并跳过任何已存在的输出。
• 原子写入。 文件先以临时名称写入，再移至目标位置，因此失败时不会留下写入不完整的文件。
• 仅限本地。 Lathe 不会建立网络连接，ffmpeg 和 ffprobe 也只会打开本地文件。
• 大小限制。 超过 LATHE_MAX_FILE_MB（默认为 500 MB）的输入会被拒绝。

安全

有关如何报告问题以及 Lathe 不会做什么，请参阅 SECURITY.md。~/.local/state/lathe/approvals.jsonl 中的审批日志会记录每项请求、批准、拒绝和回绝，但绝不会记录文件内容。

tool-manifest.lock.json 会记录每个工具描述、提示词和服务指令的哈希值。运行 python3 scripts/tool_lock.py --check 可查看自发布以来是否有任何更改。

开发

uv venv -p 3.11 .venv && uv pip install -p .venv/bin/python -e '.[dev]'
.venv/bin/pytest -q
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --check

测试会自行生成所需的测试数据。需要 ffmpeg、tesseract 或 ghostscript 的测试会在相应程序缺失时跳过。

许可证

MIT。由 Seaynic Labs 制作。第三方库和程序列于 CREDITS.md。

---

由 Seaynic Labs 构建。 我们围绕企业自己的系统构建此类工具：本地优先，并由人员审批每批运行。查看定制集成。