local-image-mcp

Minimal Model Context Protocol server for local image inspection.

local-image-mcp exposes two tools for debugging workflows:

• list_local_images: scans a local directory and returns supported image files
• load_local_image: loads a local image file and returns it as MCP image content

Loaded images are also exposed as MCP resources through debug-image://... URIs, which lets compatible clients reopen the same image resource later in the session.

Supported formats

• PNG
• JPEG / JPG
• WEBP
• GIF
• BMP
• SVG

Installation

From source

npm install

Run manually

node src/index.mjs

MCP configuration example

Add the server to your MCP client configuration:

{
  "servers": {
    "local-images": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/local-image-mcp/src/index.mjs"
      ]
    }
  }
}

Tools

list_local_images

Lists supported images in a directory.

Input:

{
  "dirPath": "/absolute/path/to/images"
}

load_local_image

Loads an image file and returns it as MCP image content.

Input:

{
  "filePath": "/absolute/path/to/image.png"
}

Response content includes:

• a text confirmation
• an image item with base64 data and MIME type

Usage example

The following example shows how an AI agent can use local-image-mcp together with a Python script to automatically detect and remove a watermark from an image, keeping the subject centred.

Prompt given to the agent:

Crop the image in assets/ to remove the watermark while keeping the drawing centred. Verify the output and overwrite the original.

What the agent did:

1. Called list_local_images on assets/ to discover logo.jpg.
2. Called load_local_image to inspect the file visually.
3. Analysed pixel data to locate the watermark (a 4-pointed star in the bottom-right corner at roughly x: 944–991, y: 944–991 on a 1024×1024 image).
4. Detected the subject bounding box (x: 153–870, y: 256–808, centre ≈ 511, 532).
5. Computed a square crop centred on the subject with the right/bottom edge stopping at 940 px (just before the watermark):

from PIL import Image

img = Image.open("assets/logo.jpg")
cx, cy = 511, 532          # subject centre
half   = min(940 - cx, 940 - cy)   # 408 px
box    = (cx - half, cy - half, cx + half, cy + half)
img.crop(box).save("assets/logo.jpg", quality=95)

6. Called load_local_image again to verify the result — watermark gone, subject centred — then overwrote the original and removed the intermediate file.

Resources

Every successfully loaded image is cached for the current server session and published as a resource:

• URI format: debug-image://<encoded-absolute-path>

This is useful when an MCP client supports resource browsing or reopening previously loaded assets.

Scripts

• npm run check — syntax check for the server entrypoint

Author

Matteo Benedetto — me@enne2.net

License

This project is released under the GNU General Public License v3.0 or later. See LICENSE for the full text.

Publishing notes

Before publishing:

1. update version in package.json
2. optionally add repository metadata and homepage fields
3. publish with your preferred npm workflow

Use cases

• inspect screenshots produced by test runs
• review rendered UI snapshots from local tools
• attach visual artifacts to debugging sessions in MCP-compatible clients