MCP Server - Image

A Model Context Protocol (MCP) server that provides tools for fetching and processing images from URLs, local file paths, and numpy arrays. The server includes a tool called fetch_images that returns images as base64-encoded strings along with their MIME types.

Support Us

If you find this project helpful and would like to support future projects, consider buying us a coffee! Your support helps us continue building innovative AI solutions.

Your contributions go a long way in fueling our passion for creating intelligent and user-friendly applications.

Features
Prerequisites
Installation
Running the Server
- Direct Method
- Configure for Windsurf/Cursor
Available Tools
- Usage Examples
Debugging
Contributing
License

Features

Fetch images from URLs (http/https)
Load images from local file paths
Specialized handling for large local images
Automatic image compression for large images (>1MB)
Parallel processing of multiple images
Proper MIME type mapping for different file extensions
Comprehensive error handling and logging

Prerequisites

Python 3.10+
uv package manager (recommended)

Installation

Clone this repository
Create and activate a virtual environment using uv:

uv venv
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

Install dependencies using uv:

uv pip install -r requirements.txt

Running the Server

There are two ways to run the MCP server:

1. Direct Method

To start the MCP server directly:

uv run python mcp_image.py

2. Configure for Windsurf/Cursor

Windsurf

To add this MCP server to Windsurf:

Edit the configuration file at ~/.codeium/windsurf/mcp_config.json
Add the following configuration:

{
  "mcpServers": {
    "image": {
      "command": "uv",
        "args": ["--directory", "/path/to/mcp-image", "run", "mcp_image.py"]
    }
  }
}

Cursor

To add this MCP server to Cursor:

Open Cursor and go to Settings (Navbar → Cursor Settings)
Navigate to Features → MCP Servers
Click on + Add New MCP Server
Enter the following configuration:

{
  "mcpServers": {
    "image": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image", "run", "mcp_image.py"]
    }
  }
}

Available Tools

The server provides the following tools:

fetch_images: Fetch and process images from URLs or local file paths Parameters: image_sources: List of URLs or file paths to images Returns: List of processed images with base64 encoding and MIME types

Usage Examples

You can now use commands like:

"Fetch these images: [list of URLs or file paths]"
"Load and process this local image: [file_path]"

Examples

# URL-only test
[
  "https://upload.wikimedia.org/wikipedia/commons/thumb/7/70/Chocolate_%28blue_background%29.jpg/400px-Chocolate_%28blue_background%29.jpg",
  "https://imgs.search.brave.com/Sz7BdlhBoOmU4wZjnUkvgestdwmzOzrfc3GsiMr27Ik/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9pbWdj/ZG4uc3RhYmxlZGlm/ZnVzaW9ud2ViLmNv/bS8yMDI0LzEwLzE4/LzJmOTY3NTViLTM0/YmQtNDczNi1iNDRh/LWJlMTVmNGM5MDBm/My5qcGc",
  "https://shigacare.fukushi.shiga.jp/mumeixxx/img/main.png"
]

# Mixed URL and local file test
[
  "https://upload.wikimedia.org/wikipedia/commons/thumb/7/70/Chocolate_%28blue_background%29.jpg/400px-Chocolate_%28blue_background%29.jpg",
  "C:\\Users\\username\\Pictures\\image1.jpg",
  "https://imgs.search.brave.com/Sz7BdlhBoOmU4wZjnUkvgestdwmzOzrfc3GsiMr27Ik/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9pbWdj/ZG4uc3RhYmxlZGlm/ZnVzaW9ud2ViLmNv/bS8yMDI0LzEwLzE4/LzJmOTY3NTViLTM0/YmQtNDczNi1iNDRh/LWJlMTVmNGM5MDBm/My5qcGc",
  "C:\\Users\\username\\Pictures\\image2.jpg"
]

Debugging

If you encounter any issues:

Check that all dependencies are installed correctly
Verify that the server is running and listening for connections
For local image loading issues, ensure the file paths are correct and accessible
For "Unsupported image type" errors, verify the content type handling
Look for any error messages in the server output

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

MCP Image Server

Integrations