MCP Image Server

An intelligent MCP (Model Context Protocol) server that searches for images, labels them, combines them into a composite image, and uses Google's Gemini 2.0 Flash AI to select the best match for your query.

Features

• 🔍 Image Search: Searches multiple sources (Unsplash, Pexels, with fallback to Lorem Picsum)

• 🏷️ Smart Labeling: Labels each image (1-20) with black borders for easy identification

• 🖼️ Image Composition: Combines all images into a single grid view

• 🤖 AI Selection: Uses Google's Gemini 2.0 Flash to intelligently select the best matching image

• 📦 Base64 Output: Returns images as base64 for easy integration

Related MCP server: Gemini Image MCP

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install

3. Copy the environment template:

   copy .env.example .env

4. Edit .env and add your API keys:

   GOOGLE_AI_API_KEY=your_google_ai_api_key_here
   UNSPLASH_ACCESS_KEY=your_unsplash_access_key_here
   PEXELS_API_KEY=your_pexels_api_key_here

Getting API Keys

Google AI API Key (Required for AI selection)

1. Go to Google AI Studio

2. Create a new API key

3. Add it to your .env file as GOOGLE_AI_API_KEY

Unsplash API Key (Optional but recommended)

1. Go to Unsplash Developers

2. Create a new application

3. Get your Access Key

4. Add it to your .env file as UNSPLASH_ACCESS_KEY

Pexels API Key (Optional but recommended)

1. Go to Pexels API

2. Create a free account and get your API key

3. Add it to your .env file as PEXELS_API_KEY

Usage

Development Mode

npm run dev

Build and Run

npm run build
npm start

Using with Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-image-server": {
      "command": "node",
      "args": ["C:/path/to/your/project/build/index.js"]
    }
  }
}

Available Tools

search_and_select_best_image

Searches for images matching your query and returns the AI-selected best match.

Parameters:

• query (string, required): The search query for images

• maxImages (number, optional): Maximum number of images to search (1-20, default: 20)

Example usage in Claude:

"Search for the best image of a sunset over mountains"

How It Works

1. Search: Queries multiple image APIs (Unsplash, Pexels) for relevant images

2. Download: Downloads up to 20 images and resizes them to thumbnails

3. Label: Adds numbered labels (1-20) with black borders to each image

4. Compose: Combines all labeled images into a single grid

5. AI Analysis: Sends the composite to Google's Gemini 2.0 Flash with your original query

6. Select: AI analyzes each numbered image and selects the best match

7. Return: Downloads and returns the selected image as base64

Error Handling

• If no API keys are provided, the server uses placeholder images from Lorem Picsum

• If Google AI API is not available, it uses a fallback selection algorithm

• Failed image downloads are replaced with placeholder images

• All errors are logged to stderr for debugging

Project Structure

src/
├── index.ts                    # Main MCP server entry point
└── services/
    ├── ImageSearchService.ts   # Handles image search from various APIs
    ├── ImageProcessingService.ts # Processes and combines images
    └── AISelectionService.ts   # Uses Google AI for selection

Development

• npm run dev - Run in development mode with auto-restart

• npm run build - Build TypeScript to JavaScript

• npm run clean - Clean build directory

License

MIT License

Contributing

Feel free to submit issues and enhancement requests!