io.github.Bishop81/imagedimensions-mcp

Official

by Bishop81 · JavaScript

Audit a web page's images: natural vs rendered sizes, oversized detection, and formats.

imagedimensions-mcp (MCP Server)

An MCP server that audits images on any public web page, focusing on natural vs. rendered dimensions, detection of oversized images, and a format breakdown. It is powered by imagedimensions.com and runs server-side, enabling AI agents to check image performance during development without requiring a local browser or Chrome install.

🛠️ Key Features

Natural vs. rendered image dimension audit
Oversized-image detection
Image format breakdown
Server-side scanning for public web pages

🚀 Use Cases

Validate how images render versus their natural dimensions
Identify oversized images that may affect performance
Review image format composition on a page

⚡ Developer Benefits

Server-side operation reduces local setup requirements
Supports AI agents (e.g., Claude, Cursor, Windsurf) in development checks
Works without a local browser or Chrome install

⚠️ Limitations

Designed for auditing images on public web pages

README.md2 KBView on GitHub

imagedimensions-mcp

An MCP server that audits the images on any public web page — natural vs. rendered dimensions, oversized-image detection, and format breakdown — so AI agents (Claude, Cursor, Windsurf, etc.) can check image performance during development.

Install / run

jsonc

// Claude Desktop / any MCP client config
{
  "mcpServers": {
    "imagedimensions": {
      "command": "npx",
      "args": ["-y", "imagedimensions-mcp"]
    }
  }
}

Tool

`scan_image_dimensions`

Param	Type	Description
`url`	string (required)	Public URL of the page to audit.
`oversizedThreshold`	number (optional)	Area-overshoot ratio to flag as oversized. Default `4` (≈2× per dimension).

Returns a text report plus structured content:

total / visible image counts and CSS-background count
modern-format share (WebP + AVIF)
format breakdown
the list of oversized images (natural → rendered, overshoot ratio, format, src)
a link to the full visual report on imagedimensions.com

Example agent uses: "Audit the images on https://example.com," "Which images on this page are oversized and hurting LCP?", "What % of this site's images use modern formats?"

Why "oversized" matters

An image downloaded much larger than the box it renders into wastes bandwidth and slows Largest Contentful Paint — the most common image-performance mistake on the web. See the writeup.

Config

IMAGEDIMENSIONS_API_BASE — override the API base (default https://imagedimensions.com).

License

MIT

Install

Configuration

Environment variables

IMAGEDIMENSIONS_API_BASE

Override the scan API base. Defaults to https://imagedimensions.com.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "imagedimensions-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "imagedimensions-mcp@0.1.2"
      ],
      "env": {
        "IMAGEDIMENSIONS_API_BASE": "<YOUR_IMAGEDIMENSIONS_API_BASE>"
      }
    }
  }
}