ShortPixel Image Optimizer

What ShortPixel Image Optimizer MCP server does

ShortPixel Image Optimizer MCP server connects MCP clients to the ShortPixel SPIO API. Its available tool, optimize_image_urls, accepts one or more public image URLs and sends them to SPIO for processing. A request can include compression mode, resizing, upscaling, format conversion, CMYK-to-RGB conversion, EXIF handling, background removal, cache refresh behavior, and per-URL parameter overrides.

The tool accepts up to 100 URLs in one call. It can also echo a caller-provided returndatalist array in the response. The returned data comes from the optimization request and can include the optimized image information and reduction result.

How it works

The server runs as an HTTP service and exposes /mcp as its Streamable HTTP MCP endpoint. An MCP client first connects, discovers the available tool, and then sends JSON-RPC tool calls. The server maps those structured arguments to a request for the SPIO reducer.php endpoint at the configured ShortPixel API base URL.

Authentication is supplied per request rather than stored by the server. Clients send the user's ShortPixel API key as Authorization: Bearer <key> or with the X-ShortPixel-Api-Key header. The server forwards the key to the upstream API and does not store user keys. The chat prompt itself does not reach the service; the MCP client converts the agent's request into tool arguments first.

Setup and configuration

Running the project locally requires Node.js 20 or newer and npm. Install dependencies with npm ci, compile with npm run build, and start the HTTP service with npm start. npm run dev runs the TypeScript source through tsx without a build step.

The default listening port is 3000. Server configuration can be supplied through .env, including PORT, ALLOWED_HOSTS, SHORTPIXEL_API_URL, SHORTPIXEL_PLUGIN_VERSION, LOG_LEVEL, LOG_FORMAT, and LOG_MCP_PROTOCOL. The server .env is for service settings; do not place users' ShortPixel API keys there.

An MCP client must point to the deployed /mcp URL and attach the API key header. The repository shows a Cursor configuration using https://mcp.shortpixel.com/mcp; a local deployment can use a host such as http://localhost:3000/mcp.

Tools and capabilities

optimize_image_urls provides these request controls:

• Compression: lossless, lossy, or glossy modes.
• Waiting: return immediately or wait up to 30 seconds.
• Resizing: outer, inner, or smart-crop modes with target dimensions.
• Upscaling: factors of 2, 3, or 4.
• Output conversion: WebP, AVIF, JPEG, PNG, or GIF options.
• Image handling: background removal, CMYK-to-RGB conversion, and EXIF retention or removal.
• Per-URL overrides through a paramlist array matching the URL list.

Health and authentication checks are available separately at /health and /ping. Logging can use readable text or one JSON object per line. API keys are masked in logs, while LOG_MCP_PROTOCOL=false disables detailed MCP payload logging.

Limitations and notes

ShortPixel Image Optimizer MCP server requires public image URLs because the exposed tool passes URLs to SPIO. A ShortPixel API key is needed for authenticated optimization calls. The URL list is limited to 100 items per request, and paramlist must have a corresponding entry for each URL when used.

The service does not interpret natural-language prompts and does not retain user API keys. Streamable HTTP clients should accept both JSON and server-sent event responses. Port 3000 is shown with HTTP in the project documentation unless TLS is configured separately, such as through nginx.