image-tiler-mcp-server

MCP server that gives LLMs full-resolution vision by tiling large images and capturing full web pages before details are lost to automatic downscaling.

What You Can Do

• Visual QA for web pages. Capture a URL, tile it, and let the LLM spot misaligned elements, wrong colors, and broken layouts at full resolution. Fix the code, re-capture, and verify the fix visually.

• Mobile responsive testing. Capture at any viewport width with mobile emulation, retina scaling, and a real mobile user agent. The LLM reviews the full mobile layout tile by tile, catching responsive breakpoint issues that only appear on small screens.

• Full-resolution image analysis. Diagrams, infographics, and design mockups lose critical details when LLMs downscale them. A 3,600 x 20,220px full-page capture that Claude would crush to ~279 x 1,568 becomes 76 analyzable tiles, each at native resolution.

• Token-efficient tile inspection. Each tile gets entropy-based content classification: blank, low-detail, mixed, or high-detail. The LLM skips blank tiles entirely and focuses tokens on what matters.

• Iterative visual workflow. Capture, analyze, fix, re-capture. Versioned output directories (_v1, _v2, ...) preserve each iteration so you can compare before and after without overwriting previous results.

Quick Start

Claude Code

claude mcp add image-tiler -- npx -y image-tiler-mcp-server

image-tiler is a local alias. You can name it anything you like. image-tiler-mcp-server is the npm package that gets downloaded and run.

See Claude Code MCP docs for more info.

codex mcp add image-tiler -- npx -y image-tiler-mcp-server

[mcp_servers.image-tiler]
command = "npx"
args = ["-y", "image-tiler-mcp-server"]

{
  "image-tiler": {
    "command": "npx",
    "args": ["-y", "image-tiler-mcp-server"]
  }
}

{
  "mcpServers": {
    "image-tiler": {
      "command": "npx",
      "args": ["-y", "image-tiler-mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "image-tiler": {
      "command": "npx",
      "args": ["-y", "image-tiler-mcp-server"]
    }
  }
}

npm install -g image-tiler-mcp-server

{
  "command": "image-tiler-mcp-server"
}

git clone https://github.com/keiver/image-tiler-mcp-server.git
cd image-tiler-mcp-server
npm install
npm run build

{
  "command": "node",
  "args": ["/absolute/path/to/image-tiler-mcp-server/dist/index.js"]
}

git clone https://github.com/keiver/image-tiler-mcp-server.git
cd image-tiler-mcp-server
docker build -t image-tiler-mcp-server .

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "/path/to/your/images:/data",
    "-e", "TILER_ALLOWED_DIRS=/data",
    "image-tiler-mcp-server"
  ]
}

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-e", "TILER_DISABLE_URL_CAPTURE=1",
    "-v", "/path/to/your/images:/data",
    "-e", "TILER_ALLOWED_DIRS=/data",
    "image-tiler-mcp-server"
  ]
}

Usage

Tile an image

tile ~/source.png and analyze content

The server reads image dimensions and generates an interactive HTML preview with per-model tabs showing grid overlays, tile counts, and token estimates. Pick the model that matches your use case, and the server tiles and returns batches for analysis.

Capture a web page

capture full page screenshot of https://tomotv.app

The server launches headless Chrome, scrolls through the page to trigger lazy-loaded images (loading="lazy"), then captures a full-page screenshot (scroll-stitching pages over 16,384px). Your assistant receives each section at full resolution and can identify layout issues, misaligned elements, or broken styling that downscaling would hide.

To get only the screenshot without tiling, just ask for a screenshot and stop after the comparison step.

Test a mobile layout

capture https://tomotv.app in mobile view

This is responsive QA, not just a different viewport. The server captures with mobile: true, which sets a 390px viewport, 2x retina scale, and a mobile Safari user agent. Sites that check for mobile UA or touch capability serve their mobile layout, so the LLM reviews exactly what a real phone user sees.

Customize tiling

Presets

OpenAI note: The openai config targets the GPT-4o / o-series vision pipeline (512px tile patches). GPT-4.1 uses a fundamentally different pipeline (32x32 pixel patches) and is not currently supported. It would require a separate model config with a different calculation approach.

Gemini 3 note: Gemini 3 uses a fixed token budget per image (1,120 tokens regardless of dimensions). Tiling increases total token cost but preserves fine detail. For cases where detail isn't critical, consider sending a single image instead.

Why Tile?

You screenshot a full page, paste it into Claude, and Claude crushes it to a thumbnail. Any image with a long edge over 1,568 pixels gets auto-downscaled to fit within ~1.15 megapixels. A 3,600 x 20,220px full-page capture becomes ~279 x 1,568, losing over 99% of its pixels before the model even sees it.

GPT-4o is more forgiving but still destructive: it scales your image to fit within 2,048px, then scales the shortest side down to 768px, then tiles internally. An 8,192px-wide NASA panorama becomes ~1,456 x 768 before GPT-4o's own tiling even begins.

Gemini 1.5/2.0 handles large images natively at 768px tiles without downscaling. Gemini 3, however, caps each image at a fixed token budget (1,120 tokens) regardless of size. Tiling gives each piece its own budget.

Each tile stays within the model's sweet spot, so the LLM processes it at full resolution.

What Happens Without Tiling

Using assets/portrait.png (3,600 x 20,220, a full-page National Geographic capture) as an example:

Gemini 1.5/2.0 tiles large images natively at 768px without downscaling. For Gemini 3, tiling multiplies the total token budget by sending each tile as a separate image.

With Tiling

Using assets/landscape.png (8,192 x 4,320, NASA image gallery):