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

Or add to ~/.codex/config.toml:

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

Add to your VS Code MCP settings:

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

Add to ~/.cursor/mcp.json:

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

Add to your Claude Desktop config file:

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

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

Restart Claude Desktop after editing.

npm install -g image-tiler-mcp-server

Then use the simpler config in any client:

{
  "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

Then point your MCP config to the built file:

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

The Problem

You screenshot a full page, paste it into Claude, and Claude rejects it. Your 20,000px full-page screenshot? Claude won't even look at it. Anything over 8,000px on either dimension gets refused outright.

GPT-4o is more forgiving but still destructive: it first 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 at default resolution) 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:

| Model | What happens | Impact | |-------|-------------|--------| | Claude | Rejected, exceeds 8,000px dimension limit | Cannot analyze the image at all | | GPT-4o | Downscaled to ~365 x 2,048, then internally tiled | ~1% of original pixels survive the downscale | | Gemini 3 | Capped at 1,120 tokens per image (default) | Fixed token budget regardless of image size |

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

| Model | Tiles | Result | |-------|-------|--------| | Claude | 76 tiles at 1,092px | Every tile under 8,000px and 1,568px limits, full analysis | | GPT-4o | 135 tiles at 768px | Every tile under 2,048px, no pre-downscale needed | | Gemini 3 | 135 tiles at 768px | Each tile gets its own token budget |

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

| Model | Without tiling | With tiling | |-------|----------------|-------------| | Claude | Rejected (8,192 > 8,000px limit) | 32 tiles at 1,092px, full analysis | | GPT-4o | Downscaled to ~1,456 x 768 (~3% of pixels survive) | 66 tiles at 768px, full resolution | | Gemini 3 | Capped at 1,120 tokens | 18 tiles at 1,536px, 18x token budget |

Based on published model vision documentation as of Feb 2026: Claude vision limits · OpenAI vision guide · Gemini image understanding · Gemini media resolution

tiler

One unified tool that handles all image tiling operations. The mode is auto-detected from the parameters you provide:

• tilesDir present → Tile retrieval mode (read-only pagination)
• url or screenshotPath present → URL capture mode (screenshot + tile)
• filePath, sourceUrl, dataUrl, or imageBase64 present → Tile-image mode

Mode priority: When multiple mode params are present, the tool resolves by priority: tilesDir > url/screenshotPath > filePath/sourceUrl/dataUrl/imageBase64. Avoid passing params from different modes in the same call.

Workflow:

The tool uses a two-step process to let you choose the right model before tiling:

1. Compare - Call with only the image source. Returns a comparison table showing tile counts and token estimates for each supported model, plus an interactive HTML preview.
2. Tile - Call again with the chosen preset + outputDir from step 1, plus:
   • Image sources: re-include your original source param (filePath, sourceUrl, etc.)
   • Captures: use screenshotPath from step 1 (not the original url)

Skip the comparison step: Provide preset and outputDir on the first call to tile immediately.

Interactive model picker: Clients that support MCP elicitation get a dropdown picker instead of the comparison table.

Parameters - Image Source (tile-image mode)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | filePath | string | no* | - | Absolute or relative path to the image file | | sourceUrl | string | no* | - | HTTPS URL to download the image from (max 50MB, 30s timeout) | | dataUrl | string | no* | - | Data URL with base64-encoded image | | imageBase64 | string | no* | - | Raw base64-encoded image data |

*At least one image source is required for tile-image mode.

Parameters - URL Capture (capture mode)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | url | string | no | - | URL of the web page to capture. Requires Chrome/Chromium installed (or CHROME_PATH env var). | | screenshotPath | string | no | - | Path to a previously captured screenshot. Skips URL capture when provided. | | viewportWidth | number | no | 1280 | Browser viewport width in pixels (320-3840) | | waitUntil | string | no | "load" | When to consider the page loaded: "load", "networkidle", or "domcontentloaded" | | delay | number | no | 0 | Additional delay in ms after page load (max 30000) |

Supports scroll-stitching for pages taller than 16,384px. Automatically triggers lazy-loaded images (loading="lazy") before capture by scrolling through the page. Pages without lazy images are unaffected.

Parameters - Tile Retrieval (pagination mode)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | tilesDir | string | no | - | Path to tiles directory (returned by a previous tiling call as outputDir) | | start | number | no | 0 | Start tile index (0-based, inclusive) | | end | number | no | start + 4 | End tile index (0-based, inclusive). Max 5 tiles per batch. | | skipBlankTiles | boolean | no | true | Skip blank tiles and return a text annotation instead of an image. Set to false to include all tiles. |

Parameters - Tiling Config (shared across modes)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | preset | string | no | Auto (cheapest) | Target vision preset: "claude", "openai", "gemini", "gemini3". Auto-selects the most token-efficient preset when omitted. | | tileSize | number | no | Model default | Tile size in pixels. Clamped to model's supported range with a warning if out of bounds. | | maxDimension | number | no | 10000 | Max dimension in px (0 to disable, or 256-65536). Values 1-255 are silently clamped to 256. Pre-downscales the image so its longest side fits within this value before tiling. | | outputDir | string | no | See below | Directory to save tiles. Defaults: for filePath sources, tiles/{name}_vN/ next to source (auto-incrementing: _v1, _v2, ..., _vN); for sourceUrl/dataUrl/imageBase64, {base}/tiles/tiled_{timestamp}_{hex}/; for captures, {base}/tiles/capture_{timestamp}_{hex}/. {base} is ~/Desktop, ~/Downloads, or ~ (first available). | | page | number | no | 0 | Tile page to return (0 = first 5, 1 = next 5, etc.) | | format | string | no | "webp" | Output format: "webp" (smaller, default) or "png" (lossless) | | includeMetadata | boolean | no | true | Analyze each tile using Shannon entropy and return content classification (blank, low-detail, mixed, high-detail) plus entropy and sharpness values per tile | | model | string | no | - | Deprecated. Use preset instead. Still accepted; emits a deprecation warning in the response. |