GetWebP MCP Server

Connect AI coding assistants to GetWebP image conversion through the Model Context Protocol (MCP).

Status: Coming Soon -- The MCP server (@getwebp/mcp-server) is implemented and under testing. It will be published to npm alongside a future CLI release. The tool interfaces described below are stable and reflect the current codebase.

See also: Commands Reference | JSON Output | README

What Is MCP?#

MCP (Model Context Protocol) is an open standard that lets AI agents call local tools directly. Instead of generating shell commands for you to copy-paste, an agent with MCP access can convert images, scan directories, and check license status on its own.

Tools#

The MCP server exposes three tools. All return structured JSON that AI agents can parse directly.

convert_images#

Convert images (JPG, PNG, BMP, WebP) to optimized WebP format.

Parameters:

Response:

{
  "success": true,
  "plan": "starter",
  "total": 3,
  "succeeded": 3,
  "failed": 0,
  "skipped": 0,
  "warnings": [],
  "results": [
    {
      "file": "/path/to/photo.jpg",
      "status": "success",
      "original_size": 204800,
      "new_size": 133120,
      "saved_ratio": 0.35
    }
  ]
}

On the Free plan, the response includes an upgrade_url field pointing to getwebp.com/pricing when at least one file was processed.

Notes:

• Relative paths are resolved against the MCP server process's working directory.
• Free plan: max 10 files per run with a 3-second delay between each file (total time may exceed 30 seconds).
• Paid plans: unlimited files with parallel processing.

scan_images#

Scan a directory for convertible image files without modifying anything.

Parameters:

Response:

{
  "total": 4,
  "files": [
    {
      "path": "/project/images/hero.jpg",
      "size": 204800,
      "format": "jpg",
      "has_webp": false
    },
    {
      "path": "/project/images/logo.png",
      "size": 51200,
      "format": "png",
      "has_webp": true
    }
  ]
}

The has_webp field indicates whether a .webp file with the same name already exists in the same directory. The format field normalizes .jpeg to jpg.

get_status#

Check the current license status and plan limits. No parameters required.

Response:

{
  "activated": true,
  "expired": false,
  "plan": "starter",
  "expires_at": "2027-04-01T00:00:00.000Z",
  "limits": {
    "max_files_per_run": null,
    "concurrent_workers": 7,
    "cooldown_seconds": 0
  }
}

Installation#

Prerequisites#

• Node.js 18 or later
• License (optional): The MCP server shares the CLI's local configuration at ~/.config/getwebp/config.json. If you have already activated a license via getwebp auth <key>, the MCP server recognizes it automatically. Without a license, it runs on the Free plan.

Claude Desktop#

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "getwebp": {
      "command": "npx",
      "args": ["-y", "@getwebp/mcp-server"]
    }
  }
}

Restart Claude Desktop after saving.

Cursor#

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "getwebp": {
      "command": "npx",
      "args": ["-y", "@getwebp/mcp-server"]
    }
  }
}

Other MCP Clients#

Any MCP client that supports the stdio transport can connect. Point it at:

npx -y @getwebp/mcp-server

Faster Startup (Optional)#

npx downloads the package on first run, which may be slow due to bundled WASM dependencies. For faster cold starts, install globally:

npm install -g @getwebp/mcp-server

Then replace the command and args in your configuration:

{
  "mcpServers": {
    "getwebp": {
      "command": "getwebp-mcp"
    }
  }
}

Integration Examples#

Claude Desktop#

After configuration, you can ask Claude to work with images directly:

"Convert all images in ./src/assets to WebP at quality 90."

Claude will call convert_images with {"input": "./src/assets", "quality": 90} and report the results, including file sizes and compression ratios.

"Which images in my project haven't been converted to WebP yet?"

Claude will call scan_images with {"path": ".", "recursive": true} and filter the results by has_webp: false.

"Am I on the free plan?"

Claude will call get_status and tell you your current plan, limits, and expiry date.

Cursor#

Cursor's agent mode can use GetWebP tools during code generation workflows:

1. The agent scans the project for unconverted images using scan_images.
2. It converts them with convert_images.
3. It updates <img> tags in your source code to reference the new .webp files.

Typical Agent Workflow#

1. get_status        -- Check plan and limits
2. scan_images       -- Discover convertible files
3. convert_images    -- Convert the files
4. Report results    -- Summarize savings to the user

Architecture#

The MCP server reuses the CLI's core modules directly (not via subprocess), ensuring identical conversion behavior:

AI Client (Claude Desktop / Cursor / ...)
        | stdio (JSON-RPC)
        v
   MCP Server (Node.js)
        |-- convert_images  --> processImages()      (cli/core/processor.ts)
        |-- scan_images     --> collectImageFiles()   (cli/core/file-scanner.ts)
        |-- get_status      --> checkLicense()        (cli/core/license.ts)

• Transport: stdio (standard MCP transport, universally supported)
• Runtime: Node.js >= 18
• Package: @getwebp/mcp-server (npm)
• Binary: getwebp-mcp

Free vs Paid Plans#

Plan limits apply identically in the MCP server and the CLI.

To upgrade, purchase a license at getwebp.com/pricing and activate it:

getwebp auth <your-license-key>

The MCP server picks up the new license automatically on its next tool call.

Troubleshooting#

Server not detected by the client#

1. Verify Node.js >= 18 is installed: node --version
2. Check that the config file path is correct for your client.
3. Restart the client application after editing configuration.
4. Test manually: npx -y @getwebp/mcp-server should start without output (it communicates via stdio).

First call is slow#

WASM codecs are initialized on the first conversion. Subsequent calls within the same server session are fast.

Free plan timeout#

With the 3-second delay per file, converting 10 files takes approximately 30 seconds. Some MCP clients may have timeout settings that need adjustment for Free plan usage.

License not recognized#

The MCP server reads from ~/.config/getwebp/config.json. Ensure you have activated your license on the same machine:

getwebp auth <your-key>
getwebp status   # verify activation

Links#

• Website: getwebp.com
• Pricing: getwebp.com/pricing
• CLI Documentation: README
• MCP Protocol: modelcontextprotocol.io