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.
Table of Contents
- Features
- Prerequisites
- Installation
- Running the Server
- Available Tools
- 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.