Lathe

Lathe

Made by Seaynic Labs. Need tools like this built around your own systems? We do that.

Lathe is an MCP bundle for anyone who handles files and media. It gives your AI assistant local tools for images, PDFs, audio and video, and OCR, plus batch runs and metadata removal. The files stay on your machine.

It is a bundle: one server made of modules, each switched on or off. Modules that arrive in an update and are off by default stay off until you turn them on.

Modules

Lathe is free and MIT licensed. It has 21 tools by default and 23 with batch and privacy on.

Skills

Skills explain how to do a job well. Your AI assistant reads them as Agent Skills, or as MCP prompts in any MCP app.

First five minutes

1. Install: uvx --from "lathe-mcp[pdf,ocr]" lathe --version prints the version. Needs Python 3.11 or newer and uv.
2. Add Lathe to your client (see Add it to your MCP client). Set LATHE_WORKING_DIR to the folder with your files.
3. Run lathe --doctor (uvx --from "lathe-mcp[pdf,ocr]" lathe --doctor). It prints ok or FIX for each piece and the command that fixes it.
4. Ask your assistant to call lathe_modules. It lists every module, what is on, and what is missing.

Try these

Paste these into your assistant, after setting 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. (needs LATHE_PRIVACY_ENABLED=true)
3. Dry-run image_optimize on everything in photos/ into web/, then run it. (needs 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.

Install

Lathe needs Python 3.11 or newer. With uv you don't install anything ahead of time. Choose the extras for the modules you use:

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

Pinned to this release, for a repeatable setup:

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

Or with pip:

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

Extras: pdf (pypdf), ocr (pytesseract), full (both). The images module needs nothing extra.

Claude Code plugin

The repository is also a Claude Code plugin. Its .mcp.json pins lathe-mcp[pdf,ocr]==0.4.1, and it ships the skills in skills/. The plugin is one way to install; the MCP config below works in any client.

System programs

Lathe starts without these. lathe --doctor and the lathe_modules tool list what is missing and the command for your platform.

Settings

Set these as environment variables in your MCP client's config, or in a config file. Lathe starts without any of them.

Config file (optional). Lathe also reads ~/.config/lathe/config.toml, or the file named by LATHE_CONFIG. Environment variables win over the file.

[core]working_dir = "/Users/you/Pictures"
[ocr]lang = "eng"
[batch]enabled = true
[privacy]enabled = true

Add it to your MCP client

Every client below runs Lathe as a local process over stdio. Put the env values only where you need them.

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, or .cursor/mcp.json in a project

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

VS Code: .vscode/mcp.json (note "servers", not "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, and other clients: any client that launches a stdio MCP server. Command uvx, arguments ["--from", "lathe-mcp[pdf,ocr]", "lathe"], plus the env values above.

Over HTTP. For clients that connect to a URL instead of starting a process:

lathe --transport http --port 8765

It serves streamable HTTP at http://127.0.0.1:8765/mcp. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.

Tools

Every tool returns structured data with a published schema. Long text comes in parts: pass next_offset back as offset. Errors always read lathe.<module>.<code>: <message> Fix: <hint>.

Approval

Only batch_process asks, and only for a run of two or more files. The client shows the person one plan: the operation, the output folder, whether existing outputs may be replaced, the file count and up to ten file names. The person approves or declines once for the whole run. The model cannot answer for the person. A client that cannot show prompts gets approval_unavailable, with the setting that fixes it (LATHE_BATCH_PREAPPROVED=true).

Every other writing tool writes one new file per call without asking. None of them overwrites an existing file unless the call passes overwrite=true.

Files and safety

• Working folder. Relative paths resolve against LATHE_WORKING_DIR. Inputs and outputs must stay inside it. Symlinks that point outside are refused.
• Nothing is overwritten by accident. An output that already exists is refused unless the call passes overwrite=true. An output can never be the input file.
• Batch runs never touch their inputs. batch_process refuses an output folder that is the input folder, and it skips any output that already exists.
• Writes are atomic. A file is written under a temporary name and moved into place, so a failure never leaves a half-written file.
• Local only. Lathe makes no network connections, and ffmpeg and ffprobe only open local files.
• Size limit. Inputs over LATHE_MAX_FILE_MB (500 MB by default) are refused.

Security

See SECURITY.md for how to report a problem and what Lathe does not do. The approval log at ~/.local/state/lathe/approvals.jsonl records each request, approval, decline and refusal. It never records file contents.

tool-manifest.lock.json records a hash of every tool description, prompt and the server instructions. python3 scripts/tool_lock.py --check shows whether anything has changed since the release.

Develop

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

The tests generate their own fixtures. Tests that need ffmpeg, tesseract or ghostscript are skipped when the program is missing.

License

MIT. Made by Seaynic Labs. Third-party libraries and programs are listed in CREDITS.md.

Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.