mcp-image

mcp-image

Say "make these five photos 1200 pixels wide" or "shrink this screenshot and strip the GPS out of it" and it happens, on your machine, in a second. This MCP server does the small image jobs that otherwise send you to a web uploader: resize, convert between PNG, JPEG, BMP, GIF and TIFF, compress with a real before-and-after byte count, crop, thumbnail a folder, watermark with your business name, and drop the EXIF block a phone camera writes into every photo. No upload, no account, no native dependency, no image editor.

The image chores of a freelance business, done from chat instead of from a browser tab you would rather not hand a client photo to.

60-second install

npm publish for @theluckystrike/mcp-image is pending. Until then, the .mcpb one-click bundle or a clone+buildis the working path -- both are verified below.

One-click (.mcpb): download image.mcpb from the latest release and double-click it in Claude Desktop:https://github.com/theluckystrike/mcp-servers/releases/latest

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "image": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-image"]
    }
  }
}

Claude Code:

claude mcp add image -- npx -y @theluckystrike/mcp-image

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "image": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-image"]
    }
  }
}

The npx form above starts working the moment the package is published. Until then, use the .mcpb bundle above, orbuild from source with exactly these three commands:

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/image

Then point your client's command at node with one arg: the absolute path to servers/image/dist/index.js.

To run in Pro mode set MCP_LICENSE_KEY in the same config block, or call license_activate once with your key.

Tools

Resource: image://recent returns the last 25 operations, newest first, with the inputs, the files written and when.Prompt: prepare_for_web takes a camera-sized image down to a page-sized JPEG, drops the metadata that came with it, and reports the bytes saved.

What you can say

Worked example

You: This photo is too big for the site. Get it to 1600 wide and drop the metadata.

  image_info { path: "~/photos/DSC_0491.jpg" }
  -> 6000x4000, 24 MP, JPEG, 8.4 MB, no alpha

  image_compress {
    path: "~/photos/DSC_0491.jpg",
    max_width: 1600,
    quality: 80,
    max_bytes: 256000,
    out_path: "~/photos/DSC_0491-web.jpg"
  }
  -> 8.4 MB -> 243.7 KB (8809124 -> 249556 bytes, -97.2%)
  -> Method: JPEG quality 62 (searched down from 80 in 5 encodes to fit 250.0 KB)
     and a resize to 1600 px wide
  -> ~/photos/DSC_0491-web.jpg, 1600x1067, JPEG

The JPEG re-encode also drops the EXIF block the camera wrote, including the GPS coordinates. The original file isbyte-for-byte unchanged.

Free vs Pro

The free limit is on what gets written, not on what gets read: a 12 MP phone photo taken down to 1600 pxwide is a free call, because that is the job. Writing 12 MP back out again is the Pro one.

A tier limit is an answer, not an error, and nothing is written when one refuses a call.

Pro is a one-time $19, or $39 for every server in the collection, lifetime.

Get Pro: https://mcp.zovo.one/buy/image

quality is a JPEG parameter, and only a JPEG parameter

This is the one thing about image compression that surprises people, so the server says it in its own answer ratherthan accepting a number and quietly doing nothing with it. A JPEG throws away detail to get smaller, and qualityis the dial for how much. A PNG is lossless: there is no dial. Passing quality: 40 to a PNG output does not makea PNG 60% smaller, it makes exactly the same PNG.

So the output format follows the extension of your out_path, and that is the lever:

• out_path: "shot-small.jpg" -- quality applies, and a photo typically drops 80-95%.
• out_path: "shot-small.png" -- quality is reported as not applicable, and only max_width removes bytes.

Palette quantisation was measured as an alternative for PNG and rejected: re-encoding a 300x220 noisy PNG through a16-colour quantiser produced a larger file (115,451 bytes against 39,262), because the encoder here writes RGBAeither way and quantising only destroys the row-to-row similarity that the deflate step was exploiting. A tool thatclaims to compress and returns a bigger file is worse than a tool that says which knob exists.

image_compress therefore always reports the byte count before and after, the percentage, and the method that didthe work -- and, if the output came out larger, it says so and tells you to keep the original.

Decompression bombs are refused from the header, before anything decodes

A 4 KB PNG can declare that it is 20,000 by 20,000 pixels. Decoding it allocates 1.6 GB of RGBA and takes theprocess down before any size check written after the decode could ever run. So the declared dimensions are read outof the container header -- PNG IHDR, the JPEG SOF segment, the GIF logical screen descriptor, the BMP info header,the first TIFF IFD -- and a file over 10,000 px on a side is refused there, with the memory it would have takennamed in the message:

Error: /path/bomb.png declares 20000x20000 pixels in its PNG header and was refused before decoding:
this server caps a side at 10000 px. A small file that declares an enormous canvas is a decompression
bomb - decoding it would allocate 1526 MB of RGBA. Nothing was decoded.

The decoded size is checked again afterwards, because a header probe can come back empty on an unusual TIFF, and aguard that only sometimes runs is not a guard.

Existing files are never overwritten, and inputs are never modified

Every tool writes a new file and leaves its inputs byte-for-byte alone -- there is no in-place mode, on purpose.An out_path that already exists is refused:

Error: /path/shot-small.png already exists and nothing was written.
Pass overwrite: true to replace it, or give a different out_path.

The path is reserved with an exclusive create, not an existence check, so two processes writing the same out_pathat the same time cannot clobber each other: one wins, the other is refused and writes nothing. image_thumbnailsand image_batch_resize reserve every one of their output paths before writing any of them, so a collision on file3 does not leave files 1 and 2 behind as a half-done batch -- and the reservations are released, so nothing empty isleft on disk either.

Pass overwrite: true when replacing the file is what you want.

overwrite: true still does not let an output be an input. Writing a result back over one of its own sourcesdestroys that source -- the pixels are already decoded in memory and get written over the file they came from, so a4000 px original becomes the 512 px thumbnail and every later read of that path is quietly wrong. So an out_paththat resolves to (or shares an inode with) any input of the same call is refused before any work happens.

What "strip metadata" actually does

image_strip_metadata decodes the image and re-encodes it from the raw pixels. EXIF, GPS coordinates, the cameraand lens, the capture time, XMP packets and embedded colour profiles are not removed one by one -- they are simplynever handed to the encoder, so they cannot come out the other side. Two consequences worth knowing:

• The pixels are the same, the bytes are not. A JPEG goes through the encoder a second time, so the copy is notbit-identical to the original even though it looks the same. Keep the original if that matters.
• Every other writing tool here has the same effect as a side effect. Resizing a photo also drops its EXIF.

Limits

• Inputs over 50 MB are refused: an image decodes to width x height x 4 bytes of raw RGBA regardless of how well itis compressed on disk.
• 10,000 px per side, checked from the header first and from the decode second.
• Read and written: PNG, JPEG, BMP, GIF and TIFF, detected by magic bytes rather than by file extension. No WebP,no AVIF, no HEIC, no SVG -- there is no pure-JavaScript decoder for those that is worth shipping, and this servertakes no native dependency.
• An animated GIF is read as its first frame. This server does not do animation.
• Watermark text is drawn with the bundled Open Sans bitmap faces (8, 16, 32, 64 and 128 px), and the largest onethat fits the image is chosen. A character those faces do not carry is not drawn, so there is no CJK watermark.
• No rotation, no filters, no colour correction, no OCR, no background removal. This server does the size-and-formatjobs; it is not an image editor.

How it stores data

Only a register of what it did: ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/image/operations.json, the last 500operations, as plain JSON. Your images stay where you put them. Every write to the register runs inside an advisorylock on .../image/.lock, so two clients on one data directory cannot lose a record, and saves go to a temporaryfile and are renamed into place.

If the register is unreadable or not valid JSON it is never treated as "empty": it is moved aside byte-for-byte asoperations.json.corrupt-<timestamp> with a marker beside it. The image you asked for is still written -- the fileis on disk before the register is touched -- and the answer tells you the history could not be updated.

The watermark reads the one shared profile the whole suite uses,${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, written by business_set in mcp-invoice ormcp-docx. Nothing is invented: with no name stored and no text passed, image_watermark refuses and says which toolto run.

Privacy

All data stays local. The server reads and writes files on your machine and makes no network request of any kind --not for licensing (keys are verified offline), not for fonts, not for telemetry. A client photo you resize is neveruploaded anywhere, which is the entire reason this exists.

Pairs with

• mcp-docx -- size a logo here, then put it in the letterhead: image_resize to the headerheight, then the .docx writer picks the file up from disk.
• mcp-pdf -- shrink the scans before you merge them, so the joined PDF is not 40 MB.
• mcp-resume -- one correctly sized, metadata-free headshot for the CV and the application form.
• office-suite -- several servers behind one install, one config entry.

Troubleshooting

• npx hangs or fails to find the package: npm publish for this package is pending. Use the .mcpb bundle orthe clone-and-build path above until it lands.
• "quality does not apply to a PNG output": write to a .jpg out_path, or pass max_width. See the sectionabove.
• "declares NxN pixels ... and was refused before decoding": the file claims a canvas over 10,000 px per side.If it is genuinely that large, resize it with a tool that streams tiles; this server decodes whole images.
• "does not start with the magic bytes": the file is not a PNG, JPEG, BMP, GIF or TIFF. A .png name on a WebPfile is the usual cause; convert it first.
• "already exists and nothing was written": pass overwrite: true, or a different out_path.
• The watermark is tiny: the largest bundled face is 128 px, and it is chosen to fit within 80% of the imagewidth. On a very large photo, resize first and watermark second.
• Node version: requires Node >= 18. Check with node -v.

MIT licensed. Support: [email protected]

Built by theluckystrike.