ShortPixel Image Optimizer

ShortPixel MCP サーバー

AI エージェント（Cursor、Claude Desktop、VS Code など）に ShortPixel SPIO の画像最適化機能を提供する、公開 HTTP MCP サーバーです。

アーキテクチャ

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)

各リクエストには、ユーザー自身の ShortPixel API キーが含まれます。MCP サーバーはユーザーのキーを保存せず、公開 SPIO API に転送します。

要件

• Node.js 20+
• npm

インストール（サーバー）

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

サーバー設定（ポート、許可するホスト、上流 API URL）については、.env を編集してください。サーバーの .env にユーザーの API キーを絶対に設定しないでください。

実行

npm start

エンドポイント：

パス	メソッド	説明
/health	GET	ヘルスチェック（API キー不要）
/ping	GET	認証チェック — API キーヘッダーがある場合に ok を返します
/mcp	POST	MCP Streamable HTTP エンドポイント

簡単なテスト（curl）

サーバー起動中、API キーなし：

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

API キーあり（簡易チェック）：

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

nginx で TLS を設定していない限り、ポート 3000 では https:// ではなく http:// を使用してください。

MCP リクエスト（重要：Streamable HTTP クライアントは JSON と 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":{}}'

認証

すべての MCP リクエストでユーザーの ShortPixel API キーを送信してください：

Authorization: Bearer <shortpixel_api_key>

代替ヘッダー：

X-ShortPixel-Api-Key: <shortpixel_api_key>

API キーをお持ちでない場合は、shortpixel.com で取得できます。

Cursor のセットアップ（エンドユーザー向け）

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

開発中は、URL をデプロイ先のホスト（例：http://localhost:3000/mcp）に置き換えてください。

サーバー環境変数

変数	必須	デフォルト	説明
PORT	いいえ	3000	HTTP リッスンポート
ALLOWED_HOSTS	いいえ	—	Host ヘッダーの許可リスト（カンマ区切り。本番環境での使用を推奨）
SHORTPIXEL_API_URL	いいえ	https://api.shortpixel.com/v2	上流 SPIO API のベース URL
SHORTPIXEL_PLUGIN_VERSION	いいえ	MCP01	SPIO に送信するプラグインバージョン
LOG_LEVEL	いいえ	info	ログの詳細度：debug、info、warn、error
LOG_FORMAT	いいえ	text	text = 人が読める形式の行、json = 構造化 JSON
LOG_MCP_PROTOCOL	いいえ	true	送受信する MCP JSON-RPC ペイロードをログに記録

ShortPixel の社内開発では、SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2 を設定してください。

リクエストログ

ログは stdout に出力されます。shortpixel-mcp systemd サービスでは /var/log/shortpixel/mcp.log にリダイレクトされます（ローカルで実行する場合は、npm start で直接表示されます）。

デフォルト（LOG_FORMAT=text） — 流れを追える説明形式のログです：

[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 にすると、概要レベルのアプリログのみが残り、MCP ペイロードのダンプは表示されません。

構造化（LOG_FORMAT=json） — 1 行につき 1 つの JSON オブジェクトです：

イベント	発生タイミング
http_request	各リクエスト（メソッド、パス、ステータス、処理時間、MCP メソッド／ツール）
spio_request	SPIO reducer.php への送信リクエスト
spio_response	SPIO の結果概要（ステータス、改善率）
mcp_auth_missing	API キーのないリクエスト

API キーはマスクされます（****abcd）。完全なキーがログに記録されることはありません。

注： チャットのプロンプトがこのサーバーに届くことはありません。LLM（MCP クライアント内）がユーザーのテキストを構造化された tools/call に変換します。サーバーが受け取るのは JSON-RPC 引数のみで、それらを SPIO API に対応付けます。

tail -f /var/log/shortpixel/mcp.log
# or, running locally
npm start

tools/list と追加の HTTP ログを記録するには、LOG_LEVEL=debug を設定してください。

デプロイ

shortpixel-mcp systemd サービス（ユニットファイルは /etc/systemd/system/shortpixel-mcp.service）として実行されます。このサービスは node dist/index.js を直接実行し（pm2 は使用しません）、プロジェクトディレクトリ内の .env から環境変数を読み込みます（EnvironmentFile=）。

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

依存関係を変更した後は、package.json と package-lock.json を再アップロードしてください。それでもビルドに失敗する場合は、npm ci --include=dev を実行してください（サーバーによっては NODE_ENV=production が設定されており、devDependencies がスキップされます）。

利用可能な MCP ツール

ツール	説明
optimize_image_urls	SPIO reducer API を通じて、1 つ以上の公開画像 URL を最適化します

optimize_image_urls の引数：

• urls（必須）：最適化する公開画像 URL（最大 100 件）
• lossy：圧縮レベル（0 可逆、1 非可逆、2 グロッシー）
• wait：最大待機秒数（0 は即時に返し、1-30 は待機）
• upscale：アップスケール倍率（0、2、3、4）
• resize：リサイズモード（0 なし、1 外接、3 内接、4 スマートクロップ）
• resize_width、resize_height：リサイズ後の目標寸法（ピクセル単位）
• cmyk2rgb：CMYK から RGB に変換（1 ははい、0 はいいえ）
• keep_exif：EXIF メタデータを保持（1 は保持、0 は削除）
• convertto：変換値（+webp、+avif、+webp|+avif、webp|avif、jpg、png、gif）
• bg_remove：背景の削除（1、画像 URL、または #rrggbbxx）
• refresh：ソースを強制的に再取得（1）するか、キャッシュされた最適化済みデータを使用（0）します
• paramlist：URL ごとのオーバーライド配列（urls と同じ長さである必要があります）
• returndatalist：レスポンスで変更せずに返す任意の配列

プロジェクト構成

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

命名規則

種類	スタイル	例
ファイル	ケバブケース	spio-api-client.ts
クラス	パスカルケース	SpioApiClient
メソッド	キャメルケース	optimizeUrls

スクリプト

コマンド	説明
npm run build	TypeScript を dist/ にコンパイルします
npm start	HTTP MCP サーバーを実行します
npm run dev	tsx で実行します（ビルド手順なし）