Skip to main content

Lathe

Lathe is an MCP bundle for anyone who handles files and media. It gives an AI assistant local tools for images, PDFs, audio and video, and OCR, so the files never leave your machine.

It is a bundle: one server made of modules. Each module can be switched on or off. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.

Module What it does Status
images Info, resize, convert, optimize, crop and thumbnail. Pillow, always available. 0.3, ready
pdf Info, text extraction (with OCR for scanned pages), merge, and rendering pages to images 0.3, ready
media Audio and video info, audio conversion, and a frame from a video (ffmpeg) 0.3, ready
ocr Read the text in an image (Tesseract) 0.3, ready

Lathe is free and MIT licensed. All 17 tools are included.

Lathe works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others.

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 and media
uvx --from "lathe-mcp[pdf,ocr]" lathe --version       # with PDF and OCR

Or with pip:

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

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

System programs

Some tools call programs that Python cannot install for you. Lathe starts without them. The lathe_modules tool lists what is missing and the command for your platform.

Program Used by macOS Debian / Ubuntu
ffmpeg (includes ffprobe) media brew install ffmpeg apt install ffmpeg
tesseract ocr, and pdf_extract_text on scanned pages brew install tesseract apt install tesseract-ocr
ghostscript pdf_to_images brew install ghostscript 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 Module What it is
LATHE_WORKING_DIR core The folder Lathe reads from and writes to. Default: the folder the server starts in.
LATHE_MAX_FILE_MB core Largest input file, in MB. Default 500.
LATHE_OCR_LANG ocr Tesseract language code(s), e.g. eng or eng+fra. Default eng.
LATHE_<MODULE>_ENABLED any false turns a module off, e.g. LATHE_MEDIA_ENABLED=false. Default true for all four modules.

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"

[media]
enabled = false

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" }
    }
  }
}

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 What it does
health Server version, working folder, and whether each external program is installed
lathe_modules Which modules are on, what is missing (with the install command), and what each tool needs. Call this first.
image_info Width, height, format, mode, size, and EXIF tags
image_resize Resize by width, height or percentage, keeping the aspect ratio
image_convert Convert to png, jpeg, webp, avif or bmp
image_optimize Shrink for web delivery; metadata stripped unless strip_metadata=false
image_crop Crop a rectangle
image_thumbnail Fit inside a square
pdf_info Page count, size, encryption, title, author
pdf_extract_text Text of all or some pages; OCR for pages without a text layer; long text in parts
pdf_merge Merge PDFs in order
pdf_to_images Render pages to PNG or JPEG at a chosen DPI
audio_info Duration, format, bitrate, sample rate, channels
audio_convert Convert to mp3, wav, flac, aac or ogg
video_info Duration, resolution, codec, frame rate, audio tracks
video_thumbnail Save one frame at a time in seconds
ocr_image Text from an image; long text in parts

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

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.
  • 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 runs on your machine, sends nothing anywhere and keeps no data.
  • Size limit. Inputs over LATHE_MAX_FILE_MB (500 MB by default) are refused.

Develop

uv venv -p 3.11 .venv && uv pip install -p .venv/bin/python -e '.[dev]'
.venv/bin/pytest -q

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

License

MIT. Published by Seaynic Labs.

Metadata

Release files for lathe-mcp 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lathe-mcp 0.3.0
File Size Uploaded Provenance Actions
lathe_mcp-0.3.0.tar.gz 89.0 kB Without provenance Details for lathe_mcp-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lathe-mcp 0.3.0
File Interpreter ABI Platform Actions
lathe_mcp-0.3.0-py3-none-any.whl Python 3 none any Details for lathe_mcp-0.3.0-py3-none-any.whl

Total release size: 114.0 kB

Release files / lathe_mcp-0.3.0.tar.gz

Download URL lathe_mcp-0.3.0.tar.gz
Size 89.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b21cb352c8024825ffac61de6bd3f4c289fe2277622de08895fc5560f73a2423
BLAKE2b-256 checksum
How to use checksums
a8c3760e628b27dcf416e874faf1a403f54196267801704b743036b4fbc0a772
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / lathe_mcp-0.3.0-py3-none-any.whl

Download URL lathe_mcp-0.3.0-py3-none-any.whl
Size 25.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88176c470730b3aa7860be57810d21e866765aa6bd90a35a7d71d046efd82d02
BLAKE2b-256 checksum
How to use checksums
a0ac7d8e627bf944e07284259d64c25c9dc3117205a38c8dbebd6bdf76283492
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for lathe-mcp 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page