ShortPixel Image Optimizer MCP server

ShortPixel MCP Server

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

Architecture

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)

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

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

Run

npm start

Endpoints:

Quick test (curl)

Server up, no API key:

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

API key present (simple check):

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):

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:

Authorization: Bearer <shortpixel_api_key>

Alternative header:

X-ShortPixel-Api-Key: <shortpixel_api_key>

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

Cursor setup (end user)

{
  "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

For internal ShortPixel development, set SHORTPIXELAPIURL=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 (LOGFORMAT=text)** — narrative flow you can follow:

Shortened. The full README is on GitHub.