Skip to main content
Glama
swtormy-agents

local-image-convert-mcp

by swtormy-agents
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

local-image-convert-mcp

A local Model Context Protocol server that converts images on your own machine. Your AI assistant can turn HEIC photos into JPEG, shrink PNGs to WebP or AVIF, or convert a whole folder into a zip, without uploading a single file.

Status: pre-release (0.1.0). Not yet published to npm.

Privacy promise

  • Nothing leaves your device. The server makes no network requests at runtime (installing or launching via npx downloads the package from the npm registry). HEIC decoding uses a WebAssembly build of libheif that ships inside the npm package; nothing is downloaded on demand.

  • No telemetry, no analytics, no logs sent anywhere. Diagnostics go only to stderr on your machine.

  • Metadata is stripped by default. Images are auto-rotated, then EXIF data (camera, GPS location, timestamps) is removed from outputs. Pass keepMetadata: true to keep it.

  • Restricted file access. The server only reads and writes inside one allowed root directory that you must set with --root; it refuses to start without one, and refuses a filesystem root (/, C:\), your home directory, or any folder that contains it (such as /home or /Users), and a root starting with an unexpanded ~ (as happens in JSON configs; use the full path); paths are compared after resolving symlinks. .. traversal, drive-relative paths, NTFS alternate data streams, reserved Windows device names (CON, PRN, AUX, NUL, COM1-9, LPT1-9, CONIN$, CONOUT$) and symlinks that resolve outside the root are rejected. Right before and after each write the output folder is re-checked. If something swaps it for a link to another location, the write is refused; if the swap happens in the instant around opening the file, the file is emptied through its open handle and an OUTPUT_DIR_CHANGED_FILE_LEFT error is returned with its location (on Linux via /proc/self/fd; on macOS and Windows the location may be unknown). If a write fails for another reason, the file is emptied and WRITE_FAILED_FILE_LEFT is returned with its path. The server never deletes files on error paths, because a name can be swapped between any check and the delete; remove leftover empty files yourself. A batch ZIP is only created after the first image converts successfully. Do not point --root at a folder that untrusted programs can modify.

  • Never overwrites. If photo.webp exists, the result is written as photo-1.webp.

Related MCP server: img-convert MCP Server

Tools

Tool

What it does

convert_image

Convert one file. Inputs: input path, format (jpeg, png, webp, avif), quality 0.5–1.0 (default 0.85), optional outputDir (default: next to the input), keepMetadata (default false).

batch_convert

Convert a list of files (inputs) and/or a folder (inputDir, not recursive) into outputDir, as separate files or one .zip (streamed to disk one image at a time) (zip: true, optional zipName using only letters, digits, ., _, -). Bad files are reported and skipped.

Supported inputs: JPEG, PNG, WebP, AVIF, GIF (first frame), TIFF, HEIC/HEIF. Both tools are annotated readOnlyHint: false, destructiveHint: false, openWorldHint: false.

Install

Requires Node.js 20 or newer.

npx -y local-image-convert-mcp --root ~/Pictures/convert

Until the package is published, run it from a clone:

git clone https://github.com/swtormy-agents/local-image-convert-mcp
cd local-image-convert-mcp && npm ci && npm run build
node dist/index.js --root ~/Pictures/convert

Configure your MCP client

Most clients (Claude Desktop, Cursor, VS Code, and others) accept a JSON config like this:

{
  "mcpServers": {
    "image-convert": {
      "command": "npx",
      "args": ["-y", "local-image-convert-mcp", "--root", "/Users/you/Pictures/convert"]
    }
  }
}

--root is required and should be an absolute path. MCP clients may start the server in an unexpected working directory. Alternatively set the environment variable LOCAL_IMAGE_CONVERT_ROOT (most clients accept an "env" object next to "args").

Options

Flag

Environment variable

Default

Meaning

--root <dir>

LOCAL_IMAGE_CONVERT_ROOT

none (required)

The only directory the server may read from and write to. A filesystem root (/, C:\), your home directory and any folder that contains it (e.g. /home, /Users) are refused, as is a path starting with an unexpanded ~ (use a full path in JSON configs)

--max-input-mb <n>

LOCAL_IMAGE_CONVERT_MAX_INPUT_MB

100

Largest input file

--max-megapixels <n>

LOCAL_IMAGE_CONVERT_MAX_MEGAPIXELS

100

Largest decoded image (protects against decompression bombs)

--max-batch-files <n>

LOCAL_IMAGE_CONVERT_MAX_BATCH_FILES

200

Most files in one batch_convert call

--no-heic

LOCAL_IMAGE_CONVERT_NO_HEIC=1

off

Kill-switch: disable HEIC/HEIF decoding (libheif is then never loaded)

Errors

Errors explain what went wrong and what to do next, for example: Path "../secret.png" is outside the allowed root (/Users/you/Pictures). Use a path inside it, or restart the server with a different --root.

Development

npm ci
npm test   # builds, then runs unit tests and a stdio smoke test

Website

A free in-browser converter by the same team: https://noclaudkit.com/

Attribution and licences

This project is MIT-licensed. HEIC decoding uses libheif and libde265 via the unmodified npm package libheif-js (LGPL-3.0), installed as a separate dependency you can replace. Raster processing uses sharp (Apache-2.0) with libvips (LGPL-3.0). HEVC/HEIC decoding only; this package never encodes HEVC or HEIC. HEVC may be covered by patents in some countries. No patent licence is granted by this project or its authors; you are responsible for any patent licences required where you use it. Full details, source links and licence texts: THIRD_PARTY_NOTICES.md and licenses/.

Disclaimer

This is an independent open-source project. Claude and Claude Desktop are trademarks of Anthropic, PBC. Cursor is a trademark of Anysphere, Inc. Visual Studio Code and VS Code are trademarks of Microsoft Corporation. All other names are trademarks of their respective owners and are used only to describe compatibility. Format names (HEIC, HEIF, WebP, AVIF, JPEG, PNG) are used descriptively. This project is not affiliated with, endorsed by, or sponsored by Anthropic, Anysphere, Microsoft or any other MCP client vendor. The software is provided "as is", without warranty of any kind (see LICENSE).

Available Tools

2 tools
batch_convertBatch convert imagesA

Convert several local images at once, from a list of paths and/or a directory (non-recursive). Writes the results as separate files or as one .zip archive into outputDir. Continues past bad files and reports each error. Runs entirely on this machine. Limit: 200 files per call.

ParametersJSON Schema
NameRequiredDescriptionDefault
zipNoPack all results into one zip file instead of separate files.
formatYesOutput format: jpeg, png, webp or avif.
inputsNoList of image paths relative to the allowed root.
qualityNoQuality 0.5-1.0 for jpeg/webp/avif (default 0.85; 1.0 = lossless for webp/avif). Ignored for png.
zipNameNoZip file name without path (default: converted.zip).
inputDirNoDirectory whose images (jpg, png, webp, avif, gif, tiff, heic) are converted. Not recursive.
outputDirYesDirectory for the results, relative to the allowed root. Created if missing.
keepMetadataNoKeep EXIF/XMP metadata such as camera and GPS data. Default false: metadata is stripped (images are auto-rotated first).

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (not read-only, not destructive, not idempotent, closed-world), and the description adds behavior beyond them: it continues past bad files and reports each error, writes into outputDir, and caps at 200 files. 'Runs entirely on this machine' mostly restates openWorldHint=false, so it is slight redundancy rather than new information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, roughly 60 words, front-loaded with purpose then mechanics. Every clause earns its place except 'Runs entirely on this machine', which duplicates the openWorldHint annotation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation-ish utility with no output schema, the description covers input sources, output destination, error behavior, and the batch limit. It omits what the tool returns (per-file results?) and any permission/'allowed root' constraint implied by the directory-relative parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters (zip vs separate files, format enum, quality, metadata handling, input/output dirs) are already fully documented in structured fields. The description adds only the aggregate notion that results go to outputDir as separate files or a single archive, which is baseline-level value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (convert) and resource (images) with explicit scope: 'several local images at once, from a list of paths and/or a directory'. The phrase 'several ... at once' implicitly but clearly distinguishes this from the singular sibling convert_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete input sources (path list and/or non-recursive directory) and a hard operational limit of 200 files per call, which helps an agent decide applicability. It never explicitly says when to prefer convert_image over this tool, so exclusions are left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_imageConvert imageA

Convert one local image (JPEG, PNG, WebP, AVIF, GIF, TIFF, HEIC/HEIF) to jpeg, png, webp or avif. Runs entirely on this machine; nothing is uploaded. Paths are relative to the allowed root (/app). Writes a new file and never overwrites existing ones. Returns the output path and sizes.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesPath of the source image, relative to the allowed root (absolute paths inside the root also work). Example: photos/IMG_0001.heic
formatYesOutput format: jpeg, png, webp or avif.
qualityNoQuality 0.5-1.0 for jpeg/webp/avif (default 0.85; 1.0 = lossless for webp/avif). Ignored for png.
outputDirNoDirectory for the result, relative to the allowed root. Created if missing. Default: same directory as the input.
keepMetadataNoKeep EXIF/XMP metadata such as camera and GPS data. Default false: metadata is stripped (images are auto-rotated first).

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (not read-only, non-destructive, not idempotent). The description adds genuinely new behavior: processing stays on the machine with nothing uploaded, a new file is always written, existing files are never overwritten, and the response returns path and sizes (valuable since there is no output schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and format enumeration are front-loaded, followed by tightly packed sentences on execution locality, path semantics, write behavior, and return value. No sentence is redundant; each adds a distinct fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-file conversion tool with no output schema, the description covers codecs, output formats, path rooting, local execution, non-overwrite behavior, and return values — everything an agent needs to invoke it correctly. The only omission, explicit batch routing, is a usage-guideline matter rather than a completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by listing supported input codecs (GIF, TIFF, HEIC/HEIF) that the output-only 'format' enum does not convey, and it reinforces the allowed-root path convention. It does not add syntax for quality or keepMetadata, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (convert) and resource (one local image), and enumerates both accepted input codecs and output formats. The word 'one' implicitly contrasts with the sibling batch_convert, giving the agent enough to tell single-file from batch conversion without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'one local image' hints at single-file scope, and the local-only/path-root constraints frame when it applies. However, there is no explicit 'use batch_convert for multiple images' routing or any when-not guidance, so the agent must infer the alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedbatch_convert
    • First observedconvert_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation5/5

convert_image and batch_convert are clearly distinguished by single-file vs multi-file operation. The descriptions make the boundary explicit (one image vs list/directory, separate files vs zip).

Naming Consistency4/5

Both names use snake_case and follow an action_object pattern (convert_image, batch_convert). The deviation is minor: 'batch' is a qualifier rather than a strict verb_noun parallel, but it reads naturally.

Tool Count4/5

With only 2 tools the surface is thin, but for a focused image conversion server the single vs batch split is a reasonable minimal scope. It is borderline rather than clearly under-provisioned.

Completeness3/5

Core conversion is covered, but there is no tool to inspect image metadata, validate paths, or list supported formats/roots. For a local conversion domain, basic CRUD-style operations beyond convert are absent, leaving some discovery dead ends.

Resources

Related MCP Connectors

Related MCP Servers