iflow-mcp_image-search 0.1.3
A Model Context Protocol server providing image search and download capabilities
License: MIT
Requires Python: ==3.12.7
Keywords: automation, download, image-search, llm, mcp

# MCP Image Search

A Model Context Protocol (MCP) server that provides image search and download capabilities for Large Language Models (LLMs).

## Features

- **Image Search**: Search for images using natural language queries
- **Automatic Download**: Download and save images to specified local paths
- **Metadata Extraction**: Retrieve image source information and metadata
- **Safe Operations**: Built-in error handling and retry mechanisms
- **Configurable API**: Support for custom API endpoints and authentication

## Tools Provided

- `image_search`: Search for images based on a query and download them to a specified path

## Installation

### Using uv (Recommended)

```bash
cd mcp-image-search
uv sync
```

### Using pip

```bash
cd mcp-image-search
pip install -e .
```

## Usage

### Command Line

```bash
# Basic usage with default settings
uv run mcp-image-search

# With custom API key
uv run mcp-image-search --api-key your-api-key

# With custom API base URL
uv run mcp-image-search --api-base-url https://your-api-endpoint.com/v1

# With custom default save path
uv run mcp-image-search --default-save-path ./my-images
```

### Configuration Options

- `--api-key`: API key for image search service
- `--api-base-url`: Base URL for the image search API (default: https://api.iflow.cn/v1)
- `--default-save-path`: Default directory to save downloaded images (default: ./images)

### Server Configuration

To use this server with MCP clients, add the following configuration to your MCP settings:

For development or when using `uv`:

```json
{
  "mcpServers": {
    "image-search": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image-search", "run", "mcp-image-search", "--api-key", "your-api-key"],
      "env": {}
    }
  }
}
```

For production deployments:

```json
{
  "mcpServers": {
    "image-search": {
      "command": "mcp-image-search",
      "args": ["--api-key", "your-api-key"],
      "env": {}
    }
  }
}
```

## Tool Usage

### image_search

Search for and download images based on a text query.

**Parameters:**
- `query` (string, required): Search query for the image (should be concise and precise)
- `save_path` (string, required): Local path where the image should be saved

**Example:**

```json
{
  "query": "sunset over mountains",
  "save_path": "./images/sunset.jpg"
}
```

**Response:**

The tool returns a text response with information about the search results, including:
- Image source and title
- Original image URL
- Local save path
- Success or error status

## API Configuration

The server uses the iFlow API by default but can be configured to work with other image search APIs. The API should return responses in the following format:

```json
{
  "code": "200",
  "data": {
    "url": "https://example.com/image.jpg",
    "originTitle": "Image Title",
    "refUrl": "https://source-website.com"
  }
}
```

## Safety Features

- **Error Handling**: Comprehensive error handling with informative messages
- **Retry Logic**: Automatic retries for failed API requests
- **Path Safety**: Automatic directory creation for save paths
- **File Management**: Automatic cleanup of existing files before saving new ones

## Development

### Setup Development Environment

```bash
cd mcp-image-search
uv sync --dev
```

### Type Checking

```bash
uv run pyright
```

### Code Formatting

```bash
uv run ruff check
uv run ruff format
```

## License

MIT License - see LICENSE file for details.