Skip to main content
Glama

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 (/.config/lathe/config.toml). Writes one local approval log (/.local/state/lathe/approvals.jsonl).

Secrets

No keys, accounts or passwords. Nothing to store, and nothing that leaves the machine.

Read-only tools

8: image_info, pdf_info, pdf_extract_text, audio_info, video_info, ocr_image, health, lathe_modules

Writes new files

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: each call writes new files in the working folder and never overwrites an existing one unless the call passes overwrite=true. batch_process asks the person once per run of two or more files, and nothing else asks.

Startup cost

about 7,600 tokens for a default install (21 tools, 4 skill prompts)

Changes

Tool descriptions are locked by hash (tool-manifest.lock.json); CI fails if they change silently.

Modules

Module

What it does

On by default

Needs

images

Info, resize, convert, optimize, crop, thumbnail

yes

Pillow (always installed)

pdf

Info, text (OCR for scanned pages), merge, render pages, split, compress

yes

pdf extra; ghostscript for rendering

media

Audio and video info, audio convert, a frame, trim, GIF

yes

ffmpeg and ffprobe

ocr

Text from an image

yes

ocr extra; tesseract

batch

One operation over every file matching a glob, dry run first

no

per operation (see above)

privacy

Inspect and remove GPS, camera and author metadata

no

pdf extra, for PDFs

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

getting-started

Setup, the install command for each missing piece, --doctor, and the approval rules

pdf

Turning a Markdown file into a PDF with Chrome or Chromium

pdf-forms

Making a PDF with fillable text boxes and checkboxes

web-image-prep

Removing location data and shrinking a folder of photos for a website

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 batch
uvx --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.

Program

Used by

macOS

Debian / Ubuntu

ffmpeg (includes ffprobe)

media, batch (audio)

brew install ffmpeg

sudo apt install ffmpeg

tesseract

ocr, and pdf_extract_text on scanned pages

brew install tesseract

sudo apt install tesseract-ocr

ghostscript

pdf_to_images, batch (PDF)

brew install ghostscript

sudo apt install 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

LATHE_WORKING_DIR

The folder Lathe reads from and writes to. Default: the folder the server starts in.

LATHE_MAX_FILE_MB

Largest input file, in MB. Default 500.

LATHE_OCR_LANG

Tesseract language code(s), e.g. eng or eng+fra. Default eng.

LATHE_<MODULE>_ENABLED

true or false. Default true for images, pdf, media and ocr; false for batch and privacy.

LATHE_BATCH_PREAPPROVED

true lets a batch run of two or more files go ahead without the approval prompt. Default false. Set it only if your client cannot show approval prompts.

LATHE_APPROVAL_LOG

Where the approval log is written. Default ~/.local/state/lathe/approvals.jsonl.

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

Tool

Module

What it does

Asks first

health

core

Server version, working folder, and whether each external program is installed

no

lathe_modules

core

Which modules are on, what is missing (with the install command), skills, and what each tool needs

no

image_info

images

Width, height, format, mode, size, and EXIF tags

no

image_resize

images

Resize by width, height or percentage, keeping the aspect ratio

no

image_convert

images

Convert to png, jpeg, webp, avif or bmp

no

image_optimize

images

Shrink for web delivery; metadata stripped unless strip_metadata=false

no

image_crop

images

Crop a rectangle

no

image_thumbnail

images

Fit inside a square

no

pdf_info

pdf

Page count, size, encryption, title, author

no

pdf_extract_text

pdf

Text of the pages you name, or of the whole file; OCR for pages without a text layer; long text in parts

no

pdf_merge

pdf

Merge PDFs in order

no

pdf_to_images

pdf

Render pages to PNG or JPEG at a chosen DPI

no

pdf_split

pdf

Split into parts of N pages

no

pdf_compress

pdf

Lossless smaller copy: content streams and duplicate objects

no

audio_info

media

Duration, format, bitrate, sample rate, channels

no

audio_convert

media

Convert to mp3, wav, flac, aac or ogg

no

video_info

media

Duration, resolution, codec, frame rate, audio tracks

no

video_thumbnail

media

Save one frame at a time in seconds

no

video_trim

media

Cut a section (stream copy; cuts land on keyframes)

no

video_to_gif

media

Animated GIF from up to 30 seconds of video

no

ocr_image

ocr

Text from an image; long text in parts

no

batch_process

batch

One operation over every matching file; dry run by default

yes, for runs of 2+ files

scrub_metadata

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_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 -q
python3 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.

Available Tools

21 tools
audio_convertA
Destructive

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_infoB
Read-only

Audio metadata: duration, format, bitrate, sample rate, channels and codec.

Inputs: input_path (required). Returns: codec, bitrate, channels, file_bytes, +3 more

healthA
Read-only

Server status, version, working directory, and whether each external piece is installed.

Inputs: no named parameters. Returns: status, version, working_dir, dependencies

image_convertB
Destructive

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_cropC
Destructive

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_infoB
Read-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_optimizeB
Destructive

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_resizeA
Destructive

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_thumbnailC
Destructive

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_modulesA
Read-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_imageA
Read-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_compressA
Destructive

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_textA
Read-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_infoC
Read-only

PDF metadata: page count, file size, encryption, title, author and creator.

Inputs: input_path (required). Returns: title, author, creator, encrypted, +2 more

pdf_mergeA
Destructive

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_splitA
Destructive

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_imagesB
Destructive

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_infoC
Read-only

Video metadata: duration, resolution, codec, frame rate, bitrate and audio tracks.

Inputs: input_path (required). Returns: fps, codec, width, height, +5 more

video_thumbnailB
Destructive

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_gifA
Destructive

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_trimA
Destructive

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

    B3.3/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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'.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      162
      92 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      29 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.
      1
      AGPL 3.0