Lathe
Lathe gives an AI assistant local, offline file/media tools for images, PDFs, audio/video, OCR, and server diagnostics.
Inspect image metadata/EXIF and create resized, converted, optimized, cropped, or thumbnail copies.
Inspect PDFs; extract text with optional OCR fallback and pagination; merge, split, compress, or render pages to PNG/JPEG.
Inspect audio/video metadata; convert audio; extract video frames; trim video; make animated GIFs.
OCR images, with language override and paginated text output.
Check server health/dependencies and list enabled modules, missing dependencies, settings, and tool availability.
File-writing tools write new files only and do not overwrite unless
overwrite=true; reads/writes stay inside the configured working folder.
Uses FFmpeg and ffprobe to inspect audio and video files, convert audio formats, and extract a frame from a video.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Lathe resize vacation-photo.jpg to 800px wide and save it as webp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Security card | |
Network | None. Lathe makes no network connections, and ffmpeg and ffprobe are restricted to local files (-protocol_whitelist file,pipe). --transport http listens on 127.0.0.1 only when you start it that way. |
Files | Reads and writes files only inside the working folder (LATHE_WORKING_DIR). Reads its optional config file ( |
Secrets | No keys, accounts or passwords. Nothing to store, and nothing that leaves the machine. |
Read-only tools | 8: |
Writes new files |
|
Startup cost | about 7,600 tokens for a default install (21 tools, 4 skill prompts) |
Changes | Tool descriptions are locked by hash ( |
Modules
Module | What it does | On by default | Needs |
| Info, resize, convert, optimize, crop, thumbnail | yes | Pillow (always installed) |
| Info, text (OCR for scanned pages), merge, render pages, split, compress | yes |
|
| Audio and video info, audio convert, a frame, trim, GIF | yes | ffmpeg and ffprobe |
| Text from an image | yes |
|
| One operation over every file matching a glob, dry run first | no | per operation (see above) |
| Inspect and remove GPS, camera and author metadata | no |
|
Lathe is free and MIT licensed. It has 21 tools by default and 23 with batch and privacy on.
Related MCP server: S3eidat Tools MCP
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.
Skill | Use it for |
| Setup, the install command for each missing piece, |
| Turning a Markdown file into a PDF with Chrome or Chromium |
| Making a PDF with fillable text boxes and checkboxes |
| Removing location data and shrinking a folder of photos for a website |
First five minutes
Install:
uvx --from "lathe-mcp[pdf,ocr]" lathe --versionprints the version. Needs Python 3.11 or newer and uv.Add Lathe to your client (see Add it to your MCP client). Set
LATHE_WORKING_DIRto the folder with your files.Run
lathe --doctor(uvx --from "lathe-mcp[pdf,ocr]" lathe --doctor). It printsokorFIXfor each piece and the command that fixes it.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:
Call lathe_modules and tell me which pieces are missing.Show me the metadata in photos/trip.jpg, then make a copy without it as photos/trip-clean.jpg.(needsLATHE_PRIVACY_ENABLED=true)Dry-run image_optimize on everything in photos/ into web/, then run it.(needsLATHE_BATCH_ENABLED=true)Split report.pdf into parts of 5 pages in parts/.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 batch
uvx --from "lathe-mcp[pdf,ocr]" lathe --version # with PDF and OCRPinned to this release, for a repeatable setup:
uvx --from "lathe-mcp[pdf,ocr]==0.4.1" lathe --versionOr 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.
Program | Used by | macOS | Debian / Ubuntu |
ffmpeg (includes ffprobe) |
|
|
|
tesseract |
|
|
|
ghostscript |
|
|
|
Settings
Set these as environment variables in your MCP client's config, or in a config file. Lathe starts without any of them.
Variable | What it is |
| The folder Lathe reads from and writes to. Default: the folder the server starts in. |
| Largest input file, in MB. Default 500. |
| Tesseract language code(s), e.g. |
|
|
|
|
| Where the approval log is written. Default |
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 = trueAdd 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]" latheCursor: ~/.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 8765It 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
Tool | Module | What it does | Asks first |
| core | Server version, working folder, and whether each external program is installed | no |
| core | Which modules are on, what is missing (with the install command), skills, and what each tool needs | no |
| images | Width, height, format, mode, size, and EXIF tags | no |
| images | Resize by width, height or percentage, keeping the aspect ratio | no |
| images | Convert to png, jpeg, webp, avif or bmp | no |
| images | Shrink for web delivery; metadata stripped unless | no |
| images | Crop a rectangle | no |
| images | Fit inside a square | no |
| Page count, size, encryption, title, author | no | |
| Text of the pages you name, or of the whole file; OCR for pages without a text layer; long text in parts | no | |
| Merge PDFs in order | no | |
| Render pages to PNG or JPEG at a chosen DPI | no | |
| Split into parts of N pages | no | |
| Lossless smaller copy: content streams and duplicate objects | no | |
| media | Duration, format, bitrate, sample rate, channels | no |
| media | Convert to mp3, wav, flac, aac or ogg | no |
| media | Duration, resolution, codec, frame rate, audio tracks | no |
| media | Save one frame at a time in seconds | no |
| media | Cut a section (stream copy; cuts land on keyframes) | no |
| media | Animated GIF from up to 30 seconds of video | no |
| ocr | Text from an image; long text in parts | no |
| batch | One operation over every matching file; dry run by default | yes, for runs of 2+ files |
| privacy | Inspect (default), or write a copy without GPS, camera or author metadata | no |
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_processrefuses 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 -q
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --checkThe 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.
Available Tools
21 toolsaudio_convertADestructive
Convert audio to mp3, wav, flac, aac or ogg. A video input keeps only its audio. The output extension must match the format.
Inputs: format (required), input_path (required), output_path (required), overwrite. Returns: format, output_path, output_bytes
audio_infoBRead-only
Audio metadata: duration, format, bitrate, sample rate, channels and codec.
Inputs: input_path (required). Returns: codec, bitrate, channels, file_bytes, +3 more
healthARead-only
Server status, version, working directory, and whether each external piece is installed.
Inputs: no named parameters. Returns: status, version, working_dir, dependencies
image_convertBDestructive
Convert an image to png, jpeg, webp, avif or bmp. The output extension must match.
Inputs: format (required), input_path (required), output_path (required), overwrite. Returns: width, format, height, output_path, +2 more
image_cropCDestructive
Crop a rectangle from an image. x and y are pixels from the top-left corner.
Inputs: x (required), y (required), width (required), height (required), +3 more. Returns: width, format, height, crop_box, +2 more
image_infoBRead-only
Image metadata: width, height, format, mode, file size, and EXIF tags (capped).
Inputs: input_path (required). Returns: exif, mode, width, format, +3 more
image_optimizeBDestructive
Shrink an image for web delivery. Metadata is stripped unless strip_metadata=false.
Inputs: input_path (required), output_path (required), quality, overwrite, +1 more. Returns: width, format, height, output_path, +3 more
image_resizeADestructive
Resize an image by width, height, or percentage. Keeps the aspect ratio when only one dimension is given. Output format comes from the output extension.
Inputs: input_path (required), output_path (required), width, height, +2 more. Returns: width, format, height, output_path, +2 more
image_thumbnailCDestructive
Make a thumbnail that fits inside a square of the given size, keeping the aspect ratio.
Inputs: input_path (required), output_path (required), size, overwrite. Returns: width, format, height, output_path, +3 more
lathe_modulesARead-only
Which modules are on, which pieces are missing (with the install command), and what each tool does. Pass a module name for its settings too.
Inputs: module. Returns: skills, modules, version, homepage, +4 more
ocr_imageARead-only
Extract the text from an image with OCR. Long text comes in parts: pass next_offset as offset to continue. lang overrides LATHE_OCR_LANG.
Inputs: input_path (required), lang, offset, max_chars. Returns: lang, text, offset, next_offset, +2 more
pdf_compressADestructive
Write a smaller copy of a PDF. Lossless: it recompresses content streams and removes duplicate objects; images are not re-encoded. Writes one new file; never overwrites unless overwrite=true.
Inputs: input_path (required), output_path (required), overwrite. Returns: pages, output_path, output_bytes, original_bytes, +1 more
pdf_extract_textARead-only
Extract text from a PDF, or from some pages ("2-5"). Pages with no text layer are read with OCR when it is installed. Long text comes in parts: pass next_offset as offset to continue.
Inputs: input_path (required), pages, offset, max_chars, +1 more. Returns: note, text, pages, method, +4 more
pdf_infoCRead-only
PDF metadata: page count, file size, encryption, title, author and creator.
Inputs: input_path (required). Returns: title, author, creator, encrypted, +2 more
pdf_mergeADestructive
Merge several PDFs, in the order given, into one new PDF.
Inputs: input_paths (required), output_path (required), overwrite. Returns: input_count, output_path, total_pages, output_bytes
pdf_splitADestructive
Split a PDF into parts of N pages each. Writes new PDFs into a folder and never overwrites one unless overwrite=true.
Inputs: input_path (required), output_dir (required), overwrite, pages_per_file. Returns: count, files, output_dir, total_pages, +1 more
pdf_to_imagesBDestructive
Render PDF pages to PNG or JPEG files in a folder, at a chosen DPI. Needs ghostscript.
Inputs: input_path (required), output_dir (required), dpi, pages, +2 more. Returns: dpi, count, format, images, +1 more
video_infoCRead-only
Video metadata: duration, resolution, codec, frame rate, bitrate and audio tracks.
Inputs: input_path (required). Returns: fps, codec, width, height, +5 more
video_thumbnailBDestructive
Save one frame of a video as a PNG or JPEG, at a time in seconds.
Inputs: input_path (required), output_path (required), overwrite, timestamp. Returns: output_path, output_bytes, timestamp_seconds
video_to_gifADestructive
Make an animated GIF from part of a video (up to 30 seconds, palette-optimized). Writes one new file; never overwrites unless overwrite=true.
Inputs: input_path (required), output_path (required), fps, start, +3 more. Returns: fps, width, output_path, output_bytes, +2 more
video_trimADestructive
Cut a section out of a video into a new file (stream copy, so it is fast and lossless; cuts land on keyframes). Never overwrites unless overwrite=true.
Inputs: input_path (required), output_path (required), end, start, +1 more. Returns: note, end_seconds, output_path, output_bytes, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool pairs a distinct resource (audio/video/image/pdf) with a clear action, so most selections are unambiguous. The only mild friction is among the image group (image_resize vs image_thumbnail vs image_optimize) and the fact that 'convert' exists for audio and image but has no video counterpart, which can prompt an agent to look for a tool that isn't there.
The dominant pattern is <resource>_<action> (audio_convert, pdf_split, image_crop, video_trim), applied consistently across all four media domains. Two outliers break the pattern: the bare 'health' and the namespace-style 'lathe_modules'.
21 tools is on the heavy side, but the server spans four distinct media domains, giving roughly 5-6 tools per domain plus two server-introspection tools. Each tool covers a concrete operation, so nothing feels padded, though a slight trim would still be possible.
Image and PDF coverage is strong (convert/resize/crop/optimize/info and merge/split/compress/extract_text/to_images/info). Notable gaps remain: there is no video_convert, video_resize, or video_compress, and no way to reorder/delete PDF pages, so agents hitting those common tasks will dead-end.
Maintenance
Related MCP Connectors
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Image and video AI tools and your own pipelines, run from any AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides local, offline transcription, keyframe extraction, OCR, and pre-publish review of audio, video, and image files, enabling AI agents to see and hear media without cloud or API keys.59 npmApache 2.0
- AlicenseAqualityBmaintenanceEnables AI assistants to work with local files — merging, compressing and editing PDFs, converting and resizing images, formatting text and data formats, running calculators, generating QR codes and barcodes, and producing invoices, resumes and other documents. Everything runs privately on the user's own machine with no uploads, accounts or API keys, and outputs can be chained from one tool to the next.16292 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to remove backgrounds, compress, resize, crop, AI-upscale, and strip metadata from images entirely on the local computer, so files never leave it.MIT
- AlicenseNot gradedqualityBmaintenance29 local file tools for AI assistants: compress, merge and split PDFs, convert and resize images, zip files, shrink and convert video. Runs on your machine, reads only folders you allow, and costs about 700 tokens up front. MIT, no account.1AGPL 3.0