ShortPixel MCP Server

Öffentlicher HTTP-MCP-Server, der die ShortPixel-SPIO-Bildoptimierung für KI-Agenten (Cursor, Claude Desktop, VS Code usw.) bereitstellt.

Architektur

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)

Jede Anfrage enthält den eigenen ShortPixel-API-Schlüssel des Benutzers. Der MCP-Server speichert keine Benutzerschlüssel – er leitet sie an die öffentliche SPIO-API weiter.

Related MCP server: img-convert MCP Server

Voraussetzungen

• Node.js 20+

• npm

Installation (Server)

npm ci
npm run build
cp .env.example .env

Bearbeiten Sie .env für Server-Einstellungen (Port, erlaubte Hosts, Upstream-API-URL). Geben Sie keine Benutzer-API-Schlüssel in die Server-.env ein.

Ausführen

npm start

Endpunkte:

Schnelltest (curl)

Server gestartet, kein API-Schlüssel:

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

API-Schlüssel vorhanden (einfache Prüfung):

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

Verwenden Sie http:// (nicht https://) auf Port 3000, sofern TLS nicht auf nginx konfiguriert ist.

MCP-Anfrage (wichtig: Streamable-HTTP-Clients müssen sowohl JSON als auch SSE akzeptieren):

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":{}}'

Authentifizierung

Senden Sie den ShortPixel-API-Schlüssel des Benutzers bei jeder MCP-Anfrage mit:

Authorization: Bearer <shortpixel_api_key>

Alternativer Header:

X-ShortPixel-Api-Key: <shortpixel_api_key>

Benutzer ohne Schlüssel erhalten einen unter shortpixel.com.

Cursor-Einrichtung (Endbenutzer)

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

Ersetzen Sie die URL während der Entwicklung durch Ihren bereitgestellten Host (z. B. http://localhost:3000/mcp).

Server-Umgebungsvariablen

Verwenden Sie für die interne ShortPixel-Entwicklung SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2.

Anfrageprotokollierung

Protokolle werden auf stdout ausgegeben (pm2 logs / npm start).

Standard (LOG_FORMAT=text) — narrative Ablaufverfolgung:

[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 behält nur App-Protokolle auf hoher Ebene und blendet MCP-Nutzlast-Ausgaben aus.

Strukturiert (LOG_FORMAT=json) — ein JSON-Objekt pro Zeile:

API-Schlüssel werden maskiert (****abcd). Vollständige Schlüssel werden nie protokolliert.

Hinweis: Der Chat-Prompt erreicht diesen Server nie. Das LLM (innerhalb des MCP-Clients) wandelt Benutzertext in einen strukturierten tools/call um; der Server sieht nur JSON-RPC-Argumente und ordnet sie der SPIO-API zu.

pm2 logs shortpixel-mcp
# or
npm start

Setzen Sie LOG_LEVEL=debug für tools/list und zusätzliche HTTP-Zeilen.

Auf dem Entwicklungsserver bereitstellen

cd /xxx/mcp.shortpixel.com
npm ci
npm run build
cp .env.example .env
# set ALLOWED_HOSTS and PORT, then run behind nginx with TLS
npm start

Laden Sie package.json und package-lock.json nach jeder Abhängigkeitsänderung erneut hoch. Wenn der Build weiterhin fehlschlägt, führen Sie npm ci --include=dev aus (manche Server setzen NODE_ENV=production, wodurch devDependencies übersprungen werden).

Verfügbare MCP-Tools

optimize_image_urls-Argumente:

• urls (erforderlich): Öffentliche Bild-URLs zur Optimierung (max. 100)

• lossy: Kompressionsstufe (0 verlustfrei, 1 verlustbehaftet, 2 glänzend)

• wait: Maximale Wartezeit in Sekunden (0 für sofortige Rückgabe, 1-30 zum Warten)

• upscale: Hochskalierungsfaktor (0, 2, 3, 4)

• resize: Größenanpassungsmodus (0 keine, 1 äußeres, 3 inneres, 4 intelligenter Zuschnitt)

• resize_width, resize_height: Zielabmessungen für die Größenanpassung in Pixeln

• cmyk2rgb: CMYK in RGB konvertieren (1 ja, 0 nein)

• keep_exif: EXIF-Metadaten behalten (1 behalten, 0 entfernen)

• convertto: Konvertierungswert (+webp, +avif, +webp|+avif, webp|avif, jpg, png, gif)

• bg_remove: Hintergrundentfernung (1, Bild-URL oder #rrggbbxx)

• refresh: Erneutes Abrufen der Quelle erzwingen (1) oder zwischengespeicherte optimierte Daten verwenden (0)

• paramlist: Array mit URL-spezifischen Überschreibungen (muss mit urls-Länge übereinstimmen)

• returndatalist: Beliebiges Array, das unverändert in der Antwort zurückgegeben wird

Projektstruktur

src/index.ts                    HTTP server entry point
src/http/auth.ts                API key extraction from requests
src/mcp/create-mcp-server.ts    Per-request MCP server factory
src/clients/spio-api-client.ts  ShortPixel SPIO HTTP client
src/tools/spio-tools.ts         MCP tools
src/http/request-log-middleware.ts HTTP request logging
src/logging/request-logger.ts    Structured JSON logger
src/logging/mcp-protocol-log.ts  MCP protocol payload capture/normalize

Namenskonventionen

Skripte