ShortPixel Image Optimizer

com.shortpixel.mcpPublished by mcp.shortpixel.comOfficial publisherv0.3.0Updated Oct 24, 2026

Optimize public image URLs via the ShortPixel SPIO API for AI agents

VerifiedStreamable HTTPWeb executableDeveloper ToolsMedia & Design

Overview

AI-generated overview

A remote MCP server that lets an assistant optimize public image URLs through the ShortPixel SPIO API, with options for compression, resizing, format conversion

What you can do
Optimize one or more public image URLs through ShortPixel, up to 100 per call, and get back the optimized image link and reduction figures. Choose compression level (lossless, lossy, glossy), wait time, upscaling, and resize mode with target width and height. Convert formats (WebP, AVIF, JPG, PNG, GIF), remove backgrounds, convert CMYK to RGB, and keep or strip EXIF metadata. Apply per-URL overrides and echo back a data list unchanged in the response.
When to use it
Useful when an assistant works with web images and needs them compressed, resized, converted, or background-removed without leaving the chat. Suited to batch optimization of up to 100 public image URLs per request.
Requirements
A remote endpoint at mcp.shortpixel.com over Streamable HTTP; no local install is needed for end users. A ShortPixel account and API key are required, sent as an Authorization bearer token (or the X-ShortPixel-Api-Key header). The image URLs must be publicly reachable.
Before you install
The ShortPixel API key is forwarded on every request to the upstream SPIO API, so treat it as a secret. Optimization consumes the user's ShortPixel account quota or credits. The server sends the supplied image URLs to a third-party API. The README notes that MCP protocol payloads are logged by default, though API keys are masked.

Installation

In SourceWeft

  1. Open ShortPixel Image Optimizer in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/com.shortpixel.mcp%2Foptimize/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "shortpixel-image-optimizer": {
      "type": "http",
      "url": "https://mcp.shortpixel.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

ShortPixel MCP Server

Public HTTP MCP server that exposes ShortPixel SPIO image optimization to AI agents (Cursor, Claude Desktop, VS Code, etc.).

Architecture

text
AI client (Cursor, Claude, …)    │    │  MCP over HTTPS (Streamable HTTP)    ▼https://mcp.shortpixel.com/mcp    │    │  user's API key in Authorization header    ▼ShortPixel SPIO API (api.shortpixel.com)

Each request carries the user's own ShortPixel API key. The MCP server does not store user keys — it forwards them to the public SPIO API.

Requirements

  • Node.js 20+
  • npm

Install (server)

bash
npm cinpm run buildcp .env.example .env

Edit .env for server settings (port, allowed hosts, upstream API URL). Do not put user API keys in server .env.

Run

bash
npm start

Endpoints:

PathMethodDescription
/healthGETHealth check (no API key)
/pingGETAuth check — returns ok if API key header is present
/mcpPOSTMCP Streamable HTTP endpoint

Quick test (curl)

Server up, no API key:

bash
curl http://mcp.shortpixel.com:3000/health

API key present (simple check):

bash
curl -i -H "Authorization: Bearer YOUR_API_KEY" http://mcp.shortpixel.com:3000/ping

Use http:// (not https://) on port 3000 unless TLS is configured on nginx.

MCP request (important: Streamable HTTP clients must accept both JSON and SSE):

bash
curl -s -N -X POST http://mcp.shortpixel.com:3000/mcp \  -H "Content-Type: application/json" \  -H "Accept: application/json, text/event-stream" \  -H "Authorization: Bearer YOUR_API_KEY" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Authentication

Send the user's ShortPixel API key on every MCP request:

http
Authorization: Bearer <shortpixel_api_key>

Alternative header:

http
X-ShortPixel-Api-Key: <shortpixel_api_key>

Users without a key can get one at shortpixel.com.

Cursor setup (end user)

json
{  "mcpServers": {    "shortpixel": {      "url": "https://mcp.shortpixel.com/mcp",      "headers": {        "Authorization": "Bearer YOUR_SHORTPIXEL_API_KEY"      }    }  }}

Replace the URL with your deployed host during development (e.g. http://localhost:3000/mcp).

Server environment variables

VariableRequiredDefaultDescription
PORTno3000HTTP listen port
ALLOWED_HOSTSno—Comma-separated Host header allowlist (recommended in production)
SHORTPIXEL_API_URLnohttps://api.shortpixel.com/v2Upstream SPIO API base URL
SHORTPIXEL_PLUGIN_VERSIONnoMCP01Plugin version sent to SPIO
LOG_LEVELnoinfoLog verbosity: debug, info, warn, error
LOG_FORMATnotexttext = human-readable lines; json = structured JSON
LOG_MCP_PROTOCOLnotrueLog inbound/outbound MCP JSON-RPC payloads

For internal ShortPixel development, set SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2.

Request logging

Logs go to stdout, which the shortpixel-mcp systemd service redirects to /var/log/shortpixel/mcp.log (npm start shows them directly when running locally).

Default (LOG_FORMAT=text) — narrative flow you can follow:

[2026-06-30 15:01:53] [1/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "initialize" (client connects) | id: 0           {             "jsonrpc": "2.0",             "method": "initialize",             "id": 0,             "params": { ... }           }[2026-06-30 15:01:53] [1/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "initialize" (client connects)[2026-06-30 15:01:53] [2/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "notifications/initialized" (session ready, no response body expected) | id: null[2026-06-30 15:01:53] [2.5/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "tools/list" (client asks which tools exist) | id: 1[2026-06-30 15:01:53] [2.5/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "tools/list" (client asks which tools exist) | tools discovered: optimize_image_urls[2026-06-30 15:02:18] [3/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "tools/call" (client runs a tool) | id: 2 | tool: "optimize_image_urls"[2026-06-30 15:02:18] [4/5] MCP → SPIO API: POST reducer.php (args mapped to SPIO payload) | ...[2026-06-30 15:02:35] [5/5] MCP ← SPIO API: Success | reduction: 27.41% | optimized: http://api.shortpixel.com/f/...-lossy.jpg | original: ...[2026-06-30 15:02:35] [3/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "tools/call" (client runs a tool) | tool: optimize_image_urls           { "jsonrpc": "2.0", "id": 2, "result": { ... } }[2026-06-30 15:02:35]     ✓ round-trip done (16.3s)

LOG_MCP_PROTOCOL=false keeps only high-level app logs and hides MCP payload dumps.

Structured (LOG_FORMAT=json) — one JSON object per line:

EventWhen
http_requestEvery request (method, path, status, duration, MCP method/tool)
spio_requestOutgoing call to SPIO reducer.php
spio_responseSPIO result summary (status, % improvement)
mcp_auth_missingRequest without API key

API keys are masked (****abcd). Full keys are never logged.

Note: The chat prompt never reaches this server. The LLM (inside the MCP client) turns user text into a structured tools/call; the server only sees JSON-RPC arguments and maps them to the SPIO API.

bash
tail -f /var/log/shortpixel/mcp.log# or, running locallynpm start

Set LOG_LEVEL=debug for tools/list and extra HTTP lines.

Deploy

Runs as the shortpixel-mcp systemd service (unit file at /etc/systemd/system/shortpixel-mcp.service), which runs node dist/index.js directly (no pm2) and reads env vars from .env in the project directory (EnvironmentFile=).

bash
cd /web/mcp.shortpixel.com   # liveVPS; a separate host from the rest of the PHP stacknpm cinpm run build# edit .env directly on the server (not deployed - gitignored)sudo systemctl restart shortpixel-mcpsudo systemctl status shortpixel-mcp

Re-upload package.json and package-lock.json after each dependency change. If build still fails, run npm ci --include=dev (some servers set NODE_ENV=production which skips devDependencies).

Available MCP tools

ToolDescription
optimize_image_urlsOptimize one or more public image URLs via SPIO reducer API

optimize_image_urls arguments:

  • urls (required): Public image URLs to optimize (max 100)
  • lossy: Compression level (0 lossless, 1 lossy, 2 glossy)
  • wait: Max wait seconds (0 to return immediately, 1-30 to wait)
  • upscale: Upscale factor (0, 2, 3, 4)
  • resize: Resize mode (0 none, 1 outer, 3 inner, 4 smart crop)
  • resize_width, resize_height: Resize target dimensions in pixels
  • cmyk2rgb: Convert CMYK to RGB (1 yes, 0 no)
  • keep_exif: Keep EXIF metadata (1 keep, 0 remove)
  • convertto: Conversion value (+webp, +avif, +webp|+avif, webp|avif, jpg, png, gif)
  • bg_remove: Background removal (1, image URL, or #rrggbbxx)
  • refresh: Force source refetch (1) or use cached optimized data (0)
  • paramlist: Per-URL overrides array (must match urls length)
  • returndatalist: Any array echoed back unchanged in response

Project layout

text
src/index.ts                    HTTP server entry pointsrc/http/auth.ts                API key extraction from requestssrc/mcp/create-mcp-server.ts    Per-request MCP server factorysrc/clients/spio-api-client.ts  ShortPixel SPIO HTTP clientsrc/tools/spio-tools.ts         MCP toolssrc/http/request-log-middleware.ts HTTP request loggingsrc/logging/request-logger.ts    Structured JSON loggersrc/logging/mcp-protocol-log.ts  MCP protocol payload capture/normalize

Naming conventions

KindStyleExample
Fileskebab-casespio-api-client.ts
ClassesPascalCaseSpioApiClient
MethodscamelCaseoptimizeUrls

Scripts

CommandDescription
npm run buildCompile TypeScript to dist/
npm startRun HTTP MCP server
npm run devRun with tsx (no build step)

Source: README.md at commit a7e387d

Tools

0
SourceWeft has not read this server's tools yet.

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.