feat: MCP wrapper server for LLM tool integration

[nagyonmarci]

Summary

I'd like to propose adding a lightweight MCP (Model Context Protocol) wrapper server so LLMs like Claude can use imgcompress as a tool directly, without a human operating the UI.

Motivation

imgcompress is a capable image processing backend, but it currently only has a browser-based frontend as its client. With the rise of AI agents and LLM-driven workflows, there's a growing need for tools that can be invoked programmatically by models. An MCP server bridges that gap — it exposes the existing REST API as structured tools that any MCP-compatible LLM can call.

Proposed approach

• Transport: stdio (the LLM client spawns the server as a local process — no new ports, no new attack surface)

• Architecture: pure proxy — no business logic, no changes to the backend. All calls go through the existing REST API, exactly as the browser does

• New dependencies: mcp[cli], httpx (Python, isolated in mcp/)

• Structure:

  mcp/
    pyproject.toml    ← dependencies (mcp[cli], httpx)
    server.py         ← FastMCP server, 6 tools
  

• Tools exposed:

  Tool	Endpoint
  compress_images	POST /api/compress
  remove_background	POST /api/compress with use_rembg=true
  download_file	GET /api/download
  download_all	GET /api/download_all
  list_supported_formats	GET /api/images_supported
  health_check	GET /api/health/backend

• Security model is unchanged: the LLM never touches the container directly. The REST API remains the only entry point — the MCP server is just a new client of it.

Example use cases

• An AI coding agent generates a logo in SVG and immediately converts and compresses it — no human in the loop
• Claude assembles a document and optimizes all images before exporting
• Batch background removal from a single prompt: "remove the background from these 20 images"

What I have ready

I have a working implementation on my fork, tested end-to-end against a running imgcompress container. Claude Desktop picks it up automatically via the standard MCP connector config. I can open a PR if this direction sounds good to you.

Questions before opening a PR

1. Is MCP integration something you'd want in the project?
2. Should mcp/ live at the repo root, or would you prefer it under a contrib/ or integrations/ directory?
3. Any preference on whether the mcp/ environment should use uv (consistent with the rest of the project) instead of plain pip?

Happy to adjust the approach based on your feedback.

[karimz1]

Hey @nagyonmarci sounds good to me.

What do you think @AlexanderSlokov regarding the security would love to hear your feedback as you added the hardening docker image in the past, so your feedback to it is also very welcome 👍

[AlexanderSlokov]

Hey @karimz1,

Thanks for pulling me in, and great proposal too, @nagyonmarci.

From a security and infrastructure perspective, here is my evaluation:

1. Contained Blast Radius:

Utilizing the existing REST API via stdio transport is the right approach. Since our current Docker Image is shell-less, the LLM is physically restricted from executing arbitrary code or spawning sub-processes, as long as the user explicitly doesn't mount external binaries or volume paths into the container.

2. Supply Chain Security:

The packages mentioned (mcp[cli], httpx) are industry standards, which is great. However, introducing new Python dependencies obviously expands our attack surface. We should carefully monitor these new additions with Docker Scout, and I would not accept the PR if high or critical CVEs show up. After all, hope is not a strategy.

3. Architectural Approach (The "Fusing" Question):

My main concern is the integration method. Fusing the MCP server into the main application container will increase the image size and introduce new potential vulnerability vectors to the core backend. To keep the core image minimal and secure, I would highly recommend keeping the MCP wrapper decoupled. We could potentially ship it as a separate lightweight mcp-wrapper image, or run it as an optional sidecar service via docker-compose.yml.

We can observe this pattern with the Grafana MCP server. Grafana has a comprehensive web UI, but their MCP server still resides in another repo and runs in a separate container.

Overall, it is a valuable addition. Happy to help review the Dockerfile/packaging approach once the PR is open!

All the bests,

Aleksandr.