# local-image-mcp

<p align="center">
  <img src="assets/logo.jpg" alt="local-image-mcp logo" width="256"/>
</p>

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

```bash
npm install
```

### Run manually

```bash
node src/index.mjs
```

## MCP configuration example

Add the server to your MCP client configuration:

```json
{
  "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:

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

### `load_local_image`

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

Input:

```json
{
  "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):

```python
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](mailto:me@enne2.net)

## License

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

## Publishing notes

Before publishing:

1. update `version` in [package.json](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