image-mcp

MCP server for advanced image processing operations with AI capabilities, local processing, and comprehensive tool discovery.

Features

• 80+ Image Processing Tools: Comprehensive toolkit for all image manipulation needs
• TypeScript MCP Server: Built with @modelcontextprotocol/sdk
• Tool Discovery System: Built-in introspection and documentation tools
• Tool Registry Pattern: Dynamic tool loading and management
• Local Processing: CPU-based operations with Sharp.js (no API keys needed)
• AI-Powered Tools: Image generation, background removal, upscaling, inpainting
• Binary Data Handling: Automatic base64 encoding for small images (<1MB)
• URL Reference Pattern: Large images (>1MB) written to disk with path references
• Batch Operations: Process multiple images efficiently
• Graceful Error Handling: Provider unavailability and timeout handling
• Cost Management: Built-in budget controls and spending alerts
• Health Monitoring: Automatic provider health checks
• File I/O Patterns: Support for file paths, URLs, and base64 input/output
• Diagram Generation: Graphviz (DOT) and Mermaid diagram rendering
• Canvas Annotations: Draw text, shapes, and labels on images

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd image-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Add your API keys (optional - local processing works without any keys):

# At minimum, add ONE AI generation provider:
SEEDREAM_API_KEY=your_key_here        # Recommended for quality
FAL_KEY=your_key_here                 # Recommended for creativity
OPENAI_API_KEY=sk-your_key_here       # Recommended for ease of use

See the Configuration Guide for detailed setup instructions.

MCP Server Setup

Add to your Claude Desktop or MCP client configuration:

{
  "mcpServers": {
    "image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/image-mcp/dist/index.js"],
      "env": {
        "SEEDREAM_API_KEY": "your_key_here",
        "FAL_KEY": "your_key_here"
      }
    }
  }
}

Verify Installation

Once connected, use the discovery tools to verify everything is working:

Use the "list_tools" tool to see all available image processing tools
Use the "list_providers" tool to check which AI providers are configured
Use the "get_capabilities" tool to see what operations are available

Tool Categories

Discovery Tools (Built-in Introspection)

• list_tools - List all available tools with descriptions and categories
• list_providers - List configured AI providers and their status
• get_tool_help - Get detailed help for a specific tool
• get_capabilities - See what operations are available with current configuration

Local Processing Tools (No API Keys Required)

• Image Manipulation: resize, crop, rotate, flip
• Format Conversion: JPEG, PNG, WebP, AVIF, TIFF, GIF
• Compression: Optimize file sizes for web and storage
• Color Adjustments: brightness, contrast, saturation, tint
• Filters: blur, sharpen, grayscale
• Watermarking: Add text or image watermarks
• Compositing: Overlay and blend images
• Metadata: Extract EXIF and image information

AI-Powered Tools (Requires API Keys)

• Image Generation: Create images from text prompts (Seedream, FLUX, DALL-E, Ideogram)
• Background Removal: Professional background removal (Photoroom, Remove.bg)
• Upscaling: AI super-resolution (Replicate)
• Inpainting: Remove objects and fill intelligently (Replicate, IOPaint)

Batch Processing Tools

• Process multiple images in parallel
• Apply transformations to entire folders
• Progress tracking and error handling

Diagram Generation Tools

• Graphviz: Generate graphs from DOT language
• Mermaid: Flowcharts, sequence diagrams, class diagrams, Gantt charts
• Specialized Diagrams: Flowcharts, dependency graphs, ER diagrams, architecture diagrams

Canvas & Annotation Tools

• Draw text with custom fonts and styles
• Add shapes (rectangles, circles, arrows)
• Label images for documentation
• Create visual annotations

Fetch & Screenshot Tools

• Fetch images from URLs
• Capture website screenshots
• Handle image downloads

Example Workflows

Web Optimization Pipeline

1. Fetch image from URL
2. Resize to target dimensions (1920x1080)
3. Compress with quality 85
4. Convert to WebP format
5. Generate thumbnail (400x300)

Social Media Export Workflow

1. Generate image with AI (landscape concept)
2. Remove background (if needed)
3. Resize for Instagram (1080x1080)
4. Resize for Twitter (1200x675)
5. Add watermark to both
6. Compress for web delivery

Screenshot Annotation Workflow

1. Fetch screenshot from URL
2. Add text labels to highlight features
3. Draw arrows pointing to key elements
4. Add rectangular highlights
5. Export as PNG for documentation

AI-Assisted Design Workflow

1. Generate base image with AI
2. Remove background
3. Upscale to high resolution
4. Adjust brightness and contrast
5. Add watermark
6. Export in multiple formats

See docs/WORKFLOWS.md for detailed workflow examples.

Documentation

• Configuration Guide - Complete setup instructions for all providers
• Usage Guide - How to use each tool category
• Workflows - Common workflow examples and patterns
• Troubleshooting - Solutions to common problems
• Architecture - Technical implementation details
• API Reference - Programmatic usage guide

Development

npm run dev   # Watch mode with hot reload
npm run lint  # Run ESLint
npm run test  # Run Jest tests
npm run format # Format code with Prettier

Adding New Tools

See docs/DEVELOPMENT.md for guide on adding new tools to the registry.

Architecture

src/
├── index.ts                    # Server entry point
├── server.ts                   # MCP server implementation
├── types.ts                    # Core type definitions
├── config/
│   ├── provider-config.ts      # API key and provider configuration
│   ├── health-monitor.ts       # Provider health monitoring
│   └── cost-tracker.ts         # Cost tracking and budget controls
├── registry/
│   └── tool-registry.ts        # Tool registry for dynamic loading
├── utils/
│   ├── binary.ts               # Binary data handling utilities
│   ├── timeout.ts              # Timeout handling utilities
│   ├── diagram-utils.ts        # Diagram generation utilities
│   └── screenshot.ts           # Screenshot capture utilities
└── tools/
    ├── discovery-tools.ts      # Tool discovery and introspection
    ├── sharp-tools.ts          # Local image processing (Sharp.js)
    ├── ai-generation-tools.ts  # AI image generation
    ├── bg-removal-tools.ts     # Background removal
    ├── upscaling-tools.ts      # AI upscaling
    ├── inpainting-tools.ts     # AI inpainting
    ├── batch-tools.ts          # Batch processing
    ├── canvas-tools.ts         # Canvas annotations
    ├── diagram-tools.ts        # Diagram generation
    ├── fetch-tools.ts          # URL fetching and screenshots
    └── example-tools.ts        # Example implementations

Cost Management

The server includes built-in cost tracking and budget controls:

# Set spending limits
PROVIDER_DAILY_COST_LIMIT=10.00
PROVIDER_MONTHLY_COST_LIMIT=100.00
PROVIDER_PER_OPERATION_LIMIT=1.00

# Enable cost alerts
PROVIDER_COST_ALERTS=true
PROVIDER_COST_ALERT_THRESHOLDS=50,75,90

See docs/COST_MANAGEMENT.md for details.

Health Monitoring

Automatic health checks keep track of provider availability:

PROVIDER_HEALTH_CHECK_ENABLED=true
PROVIDER_HEALTH_CHECK_INTERVAL=300  # 5 minutes
PROVIDER_HEALTH_CHECK_TIMEOUT=10    # 10 seconds

Use the list_providers tool with checkHealth: true to see current status.

Graceful Degradation

The server automatically falls back to alternative providers if the primary fails:

PROVIDER_GRACEFUL_DEGRADATION=true
PROVIDER_FALLBACKS=seedream:flux,dalle3;openai:replicate

Security

• API keys loaded from environment variables only
• Keys never logged or exposed in error messages
• Validation of API key format on startup
• Secure handling of temporary files
• No credential storage in code or configuration files

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT

Support

• GitHub Issues: Report bugs or request features
• Documentation: Check docs/ folder for detailed guides
• Use get_tool_help tool for specific tool documentation