# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "iflow-mcp_image-search",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.12.7",
"maintainer_email": null,
"keywords": "automation, download, image-search, llm, mcp",
"author": "MCP Image Search Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/31/01/eb41cba74b1427b6e550f7849fe79a6d5c19c80e11e5f529efb3909ed9fb/iflow_mcp_image_search-0.1.3.tar.gz",
"platform": null,
"description": "# MCP Image Search\n\nA Model Context Protocol (MCP) server that provides image search and download capabilities for Large Language Models (LLMs).\n\n## Features\n\n- **Image Search**: Search for images using natural language queries\n- **Automatic Download**: Download and save images to specified local paths\n- **Metadata Extraction**: Retrieve image source information and metadata\n- **Safe Operations**: Built-in error handling and retry mechanisms\n- **Configurable API**: Support for custom API endpoints and authentication\n\n## Tools Provided\n\n- `image_search`: Search for images based on a query and download them to a specified path\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\ncd mcp-image-search\nuv sync\n```\n\n### Using pip\n\n```bash\ncd mcp-image-search\npip install -e .\n```\n\n## Usage\n\n### Command Line\n\n```bash\n# Basic usage with default settings\nuv run mcp-image-search\n\n# With custom API key\nuv run mcp-image-search --api-key your-api-key\n\n# With custom API base URL\nuv run mcp-image-search --api-base-url https://your-api-endpoint.com/v1\n\n# With custom default save path\nuv run mcp-image-search --default-save-path ./my-images\n```\n\n### Configuration Options\n\n- `--api-key`: API key for image search service\n- `--api-base-url`: Base URL for the image search API (default: https://api.iflow.cn/v1)\n- `--default-save-path`: Default directory to save downloaded images (default: ./images)\n\n### Server Configuration\n\nTo use this server with MCP clients, add the following configuration to your MCP settings:\n\nFor development or when using `uv`:\n\n```json\n{\n \"mcpServers\": {\n \"image-search\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/mcp-image-search\", \"run\", \"mcp-image-search\", \"--api-key\", \"your-api-key\"],\n \"env\": {}\n }\n }\n}\n```\n\nFor production deployments:\n\n```json\n{\n \"mcpServers\": {\n \"image-search\": {\n \"command\": \"mcp-image-search\",\n \"args\": [\"--api-key\", \"your-api-key\"],\n \"env\": {}\n }\n }\n}\n```\n\n## Tool Usage\n\n### image_search\n\nSearch for and download images based on a text query.\n\n**Parameters:**\n- `query` (string, required): Search query for the image (should be concise and precise)\n- `save_path` (string, required): Local path where the image should be saved\n\n**Example:**\n\n```json\n{\n \"query\": \"sunset over mountains\",\n \"save_path\": \"./images/sunset.jpg\"\n}\n```\n\n**Response:**\n\nThe tool returns a text response with information about the search results, including:\n- Image source and title\n- Original image URL\n- Local save path\n- Success or error status\n\n## API Configuration\n\nThe 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:\n\n```json\n{\n \"code\": \"200\",\n \"data\": {\n \"url\": \"https://example.com/image.jpg\",\n \"originTitle\": \"Image Title\",\n \"refUrl\": \"https://source-website.com\"\n }\n}\n```\n\n## Safety Features\n\n- **Error Handling**: Comprehensive error handling with informative messages\n- **Retry Logic**: Automatic retries for failed API requests\n- **Path Safety**: Automatic directory creation for save paths\n- **File Management**: Automatic cleanup of existing files before saving new ones\n\n## Development\n\n### Setup Development Environment\n\n```bash\ncd mcp-image-search\nuv sync --dev\n```\n\n### Type Checking\n\n```bash\nuv run pyright\n```\n\n### Code Formatting\n\n```bash\nuv run ruff check\nuv run ruff format\n```\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol server providing image search and download capabilities",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [
"automation",
" download",
" image-search",
" llm",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72aeaf1c13d1b730394cb8f474e6efd991fca050c50897a8eec2e036d06b1a9f",
"md5": "3710dc37494da1ad30f76f277b022fc7",
"sha256": "386400840464e456c009563cde430597bb934e64533f626421969ff7c4d281b1"
},
"downloads": -1,
"filename": "iflow_mcp_image_search-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3710dc37494da1ad30f76f277b022fc7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.12.7",
"size": 553044,
"upload_time": "2025-09-10T08:46:28",
"upload_time_iso_8601": "2025-09-10T08:46:28.328257Z",
"url": "https://files.pythonhosted.org/packages/72/ae/af1c13d1b730394cb8f474e6efd991fca050c50897a8eec2e036d06b1a9f/iflow_mcp_image_search-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3101eb41cba74b1427b6e550f7849fe79a6d5c19c80e11e5f529efb3909ed9fb",
"md5": "7693c3fb0ee45c693e3dc6d2fa76c2eb",
"sha256": "d54e8b531a942f5b6997049ef2a0571304c59a166d68827998301576e99538b5"
},
"downloads": -1,
"filename": "iflow_mcp_image_search-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "7693c3fb0ee45c693e3dc6d2fa76c2eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.12.7",
"size": 548706,
"upload_time": "2025-09-10T08:46:29",
"upload_time_iso_8601": "2025-09-10T08:46:29.913300Z",
"url": "https://files.pythonhosted.org/packages/31/01/eb41cba74b1427b6e550f7849fe79a6d5c19c80e11e5f529efb3909ed9fb/iflow_mcp_image_search-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 08:46:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "iflow-mcp_image-search"
}
JSON