@c5t8fbt-wy/mcp-image-extractor

v1.5.10

Published

2 months ago

Enhanced MCP server for extracting and analyzing images and PDF pages from files and URLs for LLM analysis with configurable quality settings

0High
0Medium
0Low

c5t8fbt-wy

mcp model-context-protocol image pdf pdf-to-image llm smithery image-processing sharp configurable

MCP Image Extractor (Enhanced Fork)

Enhanced MCP server for extracting and analyzing images and PDFs from files and URLs for LLM analysis with configurable quality settings.

What's New in This Fork

Focus Feature - Crop specific regions of images for better detail and reduced token usage
Configurable Processing - Control image dimensions and quality via environment variables
Increased Limits - 50MB default download limit (vs 10MB in original)
Better Documentation - Comprehensive guides for optimization
Active Maintenance - Regular updates and improvements

Features

This MCP server provides tools for AI assistants to:

Extract images from local files
Extract images from URLs
NEW: Focus on specific image regions (focus_xyxy, focal_point)
NEW: Configurable dimensions (512×512 to 1568×1568)
NEW: Adjustable compression quality
NEW: Environment variable configuration

Installation

Recommended: Using npx (Easiest)

{
  "mcpServers": {
    "image-extractor": {
      "command": "npx",
      "args": ["-y", "@c5t8fbt-wy/mcp-image-extractor"],
      "env": {
        "DEFAULT_MAX_WIDTH": "1024",
        "DEFAULT_MAX_HEIGHT": "1024",
        "COMPRESSION_QUALITY": "90"
      }
    }
  }
}

Alternative: Local Installation

# Clone your fork
git clone https://github.com/C5T8fBt-WY/mcp-image-extractor_fork.git
cd mcp-image-extractor_fork
npm install
npm run build

Then configure:

{
  "mcpServers": {
    "image-extractor": {
      "command": "node",
      "args": ["c:/path/to/mcp-image-extractor_fork/dist/index.js"],
      "env": {
        "DEFAULT_MAX_WIDTH": "1024",
        "COMPRESSION_QUALITY": "90"
      }
    }
  }
}

Configuration Options

Environment Variables

| Variable | Default | Description | | ----------------------- | ---------- | --------------------------------- | | DEFAULT_MAX_WIDTH | 512 | Maximum image width (pixels) | | DEFAULT_MAX_HEIGHT | 512 | Maximum image height (pixels) | | COMPRESSION_QUALITY | 80 | JPEG/WebP quality (1-100) | | PNG_COMPRESSION_LEVEL | 9 | PNG compression (0-9, lossless) | | MAX_IMAGE_SIZE | 52428800 | Max download size (50MB in bytes) | | ALLOWED_DOMAINS | Empty | Comma-separated allowed domains |

Quality Presets

Minimal Context Usage (Default)

"env": {
  "DEFAULT_MAX_WIDTH": "512",
  "DEFAULT_MAX_HEIGHT": "512",
  "COMPRESSION_QUALITY": "80"
}

Best for: Processing many images, limited context

Balanced Quality

"env": {
  "DEFAULT_MAX_WIDTH": "768",
  "DEFAULT_MAX_HEIGHT": "768",
  "COMPRESSION_QUALITY": "85"
}

Best for: Reading small text, charts, diagrams

Maximum Quality (Claude-compatible)

"env": {
  "DEFAULT_MAX_WIDTH": "1568",
  "DEFAULT_MAX_HEIGHT": "1568",
  "COMPRESSION_QUALITY": "90",
  "MAX_IMAGE_SIZE": "104857600"
}

Best for: Detailed screenshots, technical documentation

Available Tools

extract_image_from_file

Extract and analyze images from local file paths.

Parameters:

file_path (required): Path to the image file
focus_xyxy (optional): Rectangle [x1, y1, x2, y2] - pixels (int) or ratio (0.0-1.0)
focal_point (optional): Center region [centerX, centerY, halfWidth, halfHeight] - pixels (int) or ratio (0.0-1.0)

Examples:

Analyze the test failure: test-results/checkout-failed.png

Focus on the error message in the top-right quarter:
focus_xyxy: [0.5, 0, 1, 0.25]

Focus on a specific button centered at coordinates (100, 200):
focal_point: [100, 200, 50, 30]

extract_image_from_url

Extract and analyze images from web URLs.

Parameters:

url (required): URL of the image
focus_xyxy (optional): Rectangle [x1, y1, x2, y2] - pixels (int) or ratio (0.0-1.0)
focal_point (optional): Center region [centerX, centerY, halfWidth, halfHeight] - pixels (int) or ratio (0.0-1.0)

Examples:

What's in this image? https://example.com/chart.png

Focus on the legend in bottom-left:
focus_xyxy: [0, 0.75, 0.3, 1]

Use Cases

✅ Analyzing Playwright Test Results

"Analyze this test failure screenshot: ./test-results/login-error.png"

✅ Processing External Images

"Extract the chart from https://reports.company.com/Q4-summary.png"

✅ High-Resolution Screenshots

Supports large images (up to 50MB by default)
Configurable output dimensions for quality control
Automatic format detection and optimization

✅ Focused Image Analysis

"Read the small text in the upper-right corner of screenshot.png"
With focus_xyxy: [0.7, 0, 1, 0.2] for better OCR accuracy

"What's the score on the dashboard centered at 50% width, 30% height?"
With focal_point: [0.5, 0.3, 0.1, 0.1] to zoom into that specific widget

Context Usage Examples

| Configuration | Dimensions | Approx Tokens | Use Case | | ------------- | ---------- | ------------- | -------------------- | | Default | 512×288 | ~900 | Quick analysis | | Balanced | 768×432 | ~2,100 | Charts & diagrams | | Maximum | 1568×882 | ~8,000 | Detailed screenshots |

Using with VS Code Remote SSH

When connected to a remote machine via VS Code Remote SSH, MCP servers configured in your user profile (MCP: Open User Configuration) run locally — they cannot access files on the remote machine.

To make the server run on the remote machine (so it can read remote file paths), put the config in either:

Option 1: Workspace settings (recommended, shareable)

Create or edit .vscode/mcp.json in your project root on the remote machine:

{
  "servers": {
    "image-extractor": {
      "command": "npx",
      "args": ["-y", "@c5t8fbt-wy/mcp-image-extractor"],
      "env": {
        "DEFAULT_MAX_WIDTH": "1024",
        "COMPRESSION_QUALITY": "90"
      }
    }
  }
}

VS Code will spawn this process on the remote host when you are connected via SSH. No tunnels or HTTP setup required — just add the config and click Start.

Option 2: Remote user settings (per-user, all remote workspaces)

Run MCP: Open Remote User Configuration from the Command Palette while connected to the remote. Add the same JSON as above. This applies to all workspaces on that remote host for your user account.

Why this works

VS Code runs MCP servers wherever they are configured:

| Config location | Where the process runs | |---|---| | User profile (MCP: Open User Configuration) | Local machine | | Workspace .vscode/mcp.json | Remote machine (when SSH-connected) | | Remote user settings (MCP: Open Remote User Configuration) | Remote machine |

HTTP/SSE mode (always-on / Docker)

For Docker containers or always-on server deployments, set MCP_HTTP_PORT to enable an HTTP server instead of stdio:

MCP_HTTP_PORT=3100 node dist/index.js

Then configure VS Code to connect via URL:

{
  "servers": {
    "image-extractor": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}

Endpoints: /sse (SSE stream), /messages (POST), /health (status check).

Troubleshooting

"maxContentLength exceeded" Error

Increase the download limit:

"env": {
  "MAX_IMAGE_SIZE": "104857600"
}

Images Too Blurry

Increase dimensions:

"env": {
  "DEFAULT_MAX_WIDTH": "1024",
  "DEFAULT_MAX_HEIGHT": "1024"
}

"Unsupported image format" (BMP files)

BMP files with .png extension need conversion:

# PowerShell
Add-Type -AssemblyName System.Drawing
$bmp = [System.Drawing.Image]::FromFile("path/to/file.png")
$bmp.Save("path/to/file_actual.png", [System.Drawing.Imaging.ImageFormat]::Png)
$bmp.Dispose()

Publishing to npm

This fork is published as @c5t8fbt-wy/mcp-image-extractor on npm.

To publish updates:

# Update version in package.json
npm version patch  # or minor/major

# Build
npm run build

# Publish (requires npm login)
npm publish

Differences from Original

| Feature | Original | This Fork | | ----------------------- | -------- | ------------- | | Max download size | 10MB | 50MB | | Focus/crop regions | ❌ | ✅ | | Configurable dimensions | ❌ | ✅ | | Configurable quality | ❌ | ✅ | | Environment vars | Limited | Full | | HTTP/SSE transport | ❌ | ✅ (MCP_HTTP_PORT) | | Remote SSH docs | ❌ | ✅ | | Documentation | Basic | Comprehensive |

Development

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Build
npm run build

# Run tests
npm test

License

MIT

Credits

Based on mcp-image-extractor by @ifmelate

Enhanced with configurable settings and improved documentation by @C5T8fBt-WY