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

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!