SmallPict Model Context Protocol (MCP) Server

The SmallPict MCP Server (@smallpict/mcp) implements the open Model Context Protocol standard, giving Large Language Models (LLMs) and autonomous AI coding agents native tools to inspect, compress, convert, and manage web assets directly within their workflow.

⚡ Key Highlights

• Universal Multi-Agent Support: Compatible with Claude for Desktop, Cursor, Google Antigravity (AGY), OpenCode, Windsurf, Cline / Roo Code, Goose, and any MCP-compliant runtime.
• Zero Local Compilation: Run instantly via npx -y @smallpict/mcp with Node.js 18+.
• Secure by Design: Operates over standard input/output (stdio) with error logging strictly routed to stderr to prevent JSON-RPC stream corruption.
• Dual Environment: Supports production API keys (sp_live_...) and free sandbox keys (sp_test_...) for zero-quota test operations.

🛠️ Available MCP Tools

Once installed, your AI agent automatically gains access to the following three high-performance tools:

1. smallpict_optimize_image

Compresses and converts local image files or remote URLs to next-generation formats (WebP, AVIF) with up to 88% size reduction.

2. smallpict_get_quota

Inspects your SmallPict account's active subscription tier, monthly bytes limit, and remaining bandwidth balance.

3. smallpict_purge_cdn_cache

Instantly purges edge-cached images from Cloudflare Edge CDN after updating assets.

🚀 Setup & Multi-Agent Configuration

1. Claude for Desktop

Add the smallpict server definition to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

Restart Claude Desktop, and you will see the hammer 🔨 tool icon active with SmallPict tools enabled.

2. Cursor IDE

Configure SmallPict MCP in Cursor globally or per-project:

Option A: Cursor Global Settings

1. Open Cursor Settings (Cmd + , or Ctrl + ,).
2. Navigate to Features → MCP Servers.
3. Click + Add New MCP Server.
   • Name: smallpict
   • Type: command
   • Command: npx -y @smallpict/mcp
   • Environment Variables: SMALLPICT_API_KEY=sp_live_YOUR_API_KEY

Option B: Workspace Configuration (.cursor/mcp.json)

Create a file at .cursor/mcp.json in your project root:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

3. Google Antigravity (AGY)

For developers using the Antigravity multi-agent coding environment, add the SmallPict MCP server to ~/.gemini/antigravity/mcp/smallpict/mcp.json or your workspace settings:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

Antigravity subagents can now optimize project assets autonomously during build and frontend refactoring workflows.

4. VS Code (Cline / Roo Code)

In VS Code with the Cline or Roo Code extension:

1. Open the Cline panel and click the MCP Servers icon.
2. Select Configure MCP Servers (opens cline_mcp_settings.json).
3. Add the server entry:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      },      "disabled": false,      "autoApprove": [        "smallpict_get_quota",        "smallpict_optimize_image"      ]    }  }}

5. Windsurf (Codeium)

Edit your Windsurf configuration at ~/.codeium/windsurf/mcp_config.json:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

6. OpenCode, Codex & Custom AI Runners

For terminal-based agents (Goose, OpenCode, custom LangChain / LlamaIndex scripts), invoke @smallpict/mcp directly via standard input/output:

# Launch directly in your agent subprocessSMALLPICT_API_KEY"sp_live_YOUR_KEY" npx -y @smallpict/mcp

💬 Example AI Prompts

Once configured, you can talk naturally to your AI agent without writing manual scripts:

Batch Optimize Local Assets

"Agent, find all PNG and JPEG images inside public/images/, convert them to WebP at quality 80, and give me a summary table of how many bytes we saved."

Check Account Quota

"What is my remaining SmallPict quota this month before I start bulk optimizing hero assets?"

CDN Invalidation

"I just replaced hero-banner.jpg in S3. Please purge the SmallPict CDN cache for that asset."

🧪 Testing with Sandbox Keys

You can test without consuming your monthly transformation quota by using a Sandbox key:

"env": {  "SMALLPICT_API_KEY": "sp_test_sandbox_secret_key"}

• Transforms images using the exact same production libvips engine.
• Quota is tracked in an isolated sandbox pool with zero monthly deductions.
• Assets are kept in ephemeral 24-hour test storage.