mcp_photo — MCP Image Generation Server

An MCP server for generating and editing images via the OpenRouter API. Deployed in Docker, connects to Claude Desktop through stdio transport. Supports dynamic model discovery from OpenRouter and model metadata caching for optimized performance.

Документация на русском

Features

• generate_image — generate an image from a text prompt with support for multiple models; project — organize output into output/{project}/ subfolders (optional, defaults to _default); save_dir — directory for saving output (optional, takes priority over project)
• edit_image — image-to-image editing (replacing or transforming part of an image); project — organize output into output/{project}/ subfolders (optional, defaults to _default); save_dir — directory for saving output (optional, takes priority over project)
• list_models — dynamic list of available models with pricing and parameter details

Requirements

• Python 3.11+
• Docker Desktop
• OpenRouter API key (https://openrouter.ai)

Quick Start

1. Clone the repository:

   git clone https://github.com/afr13nd77/mcp_photo.git
   cd mcp_photo
   

2. Copy .env.example to .env and add your OpenRouter API key:

   cp .env.example .env
   # Edit .env: OPENROUTER_API_KEY=sk_...
   

3. Build the container:

   docker compose build
   

4. Start the server:

   docker compose run --rm -i mcp-photo
   

Claude Desktop Integration

Add the following block to your ~/.claude/claude_desktop_config.json config:

{
  "mcpServers": {
    "mcp-photo": {
      "command": "docker",
      "args": ["compose", "-f", "I:/ai_projects/mcp_photo/docker-compose.yml", "run", "--rm", "-i", "mcp-photo"]
    }
  }
}

Supported Models

Tier	Model	ID	Price/img	Note
Tier 1	Gemini 3.1 Flash	google/gemini-3.1-flash-image	$0.00006	Default
Tier 1	Gemini 3.1 Flash Lite	google/gemini-3.1-flash-lite-image	$0.00003	Lightweight version
Tier 1	GPT-4 Vision	openai/gpt-image-2	$0.00003	OpenAI vision
Tier 1	DALL-E 3	openai/gpt-image-1	$0.00004	DALL-E generation

Note: The full list of available models and their current pricing is discovered dynamically when the list_models tool is invoked. The table above lists the most commonly used Tier 1 models.

Configuration

Variable	Type	Description	Default
OPENROUTER_API_KEY	string	OpenRouter API key	(required)
OUTPUT_DIR	string	Directory for saved images	./output
DEFAULT_MODEL	string	Default model for generate_image	google/gemini-3.1-flash-image
MODEL_CACHE_TTL	float	Model cache time-to-live (seconds)	3600
REQUEST_TIMEOUT	float	Timeout for OpenRouter requests (seconds)	120
MAX_RETRIES	int	Maximum number of retries on error	2
MAX_PROMPT_LENGTH	int	Maximum text prompt length	10000
MAX_SOURCE_IMAGE_SIZE	int	Maximum source image size (bytes)	20971520 (20 MB)
ALLOWED_DIRS	string	Comma-separated list of allowed directories for image loading	(empty — any)
LOG_LEVEL	string	Log level (DEBUG, INFO, WARNING, ERROR)	INFO

Development

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest

Lint:

ruff check .

Format:

ruff format .

Version

0.1.0 — Initial release with full MCP server functionality.

---

Документация на русском

mcp_photo — MCP-сервер генерации изображений

MCP-сервер для генерации и редактирования изображений через OpenRouter API. Развёртывается в Docker, подключается к Claude Desktop через stdio-транспорт. Поддерживает динамическое обнаружение моделей из OpenRouter и кэширование метаданных моделей для оптимизации производительности.

Возможности

• generate_image — генерация изображения по текстовому промпту с поддержкой различных моделей; project — организация в подпапки output/{project}/ (опционально, по умолчанию _default); save_dir — директория для сохранения (опционально, имеет приоритет над project)
• edit_image — image-to-image редактирование (замена или трансформация части изображения); project — организация в подпапки output/{project}/ (опционально, по умолчанию _default); save_dir — директория для сохранения (опционально, имеет приоритет над project)
• list_models — динамический список доступных моделей с информацией о ценах и параметрах

Требования

• Python 3.11+
• Docker Desktop
• OpenRouter API key (https://openrouter.ai)

Быстрый старт

1. Клонируйте репозиторий:

   git clone https://github.com/afr13nd77/mcp_photo.git
   cd mcp_photo
   

2. Скопируйте .env.example в .env и вставьте ваш OpenRouter API key:

   cp .env.example .env
   # Отредактируйте .env: OPENROUTER_API_KEY=sk_...
   

3. Соберите контейнер:

   docker compose build
   

4. Запустите сервер:

   docker compose run --rm -i mcp-photo
   

Подключение к Claude Desktop

Добавьте следующий блок в конфиг ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-photo": {
      "command": "docker",
      "args": ["compose", "-f", "I:/ai_projects/mcp_photo/docker-compose.yml", "run", "--rm", "-i", "mcp-photo"]
    }
  }
}

Поддерживаемые модели

Уровень	Модель	ID	Цена/img	Примечание
Tier 1	Gemini 3.1 Flash	google/gemini-3.1-flash-image	$0.00006	По умолчанию
Tier 1	Gemini 3.1 Flash Lite	google/gemini-3.1-flash-lite-image	$0.00003	Облегчённая версия
Tier 1	GPT-4 Vision	openai/gpt-image-2	$0.00003	OpenAI vision
Tier 1	DALL-E 3	openai/gpt-image-1	$0.00004	DALL-E generation

Примечание: полный список доступных моделей и их актуальные цены обнаруживаются динамически при запуске инструмента list_models. Таблица выше содержит Tier 1 модели, наиболее часто используемые.

Конфигурация

Переменная	Тип	Описание	По умолчанию
OPENROUTER_API_KEY	string	API ключ OpenRouter	(требуется)
OUTPUT_DIR	string	Директория для сохранённых изображений	./output
DEFAULT_MODEL	string	Модель по умолчанию для generate_image	google/gemini-3.1-flash-image
MODEL_CACHE_TTL	float	Время жизни кэша моделей (секунды)	3600
REQUEST_TIMEOUT	float	Таймаут для запросов к OpenRouter (секунды)	120
MAX_RETRIES	int	Максимальное количество повторов при ошибке	2
MAX_PROMPT_LENGTH	int	Максимальная длина текстового промпта	10000
MAX_SOURCE_IMAGE_SIZE	int	Максимальный размер исходного изображения (байты)	20971520 (20 МБ)
ALLOWED_DIRS	string	Comma-separated список допустимых директорий для загрузки изображений	(пусто — любые)
LOG_LEVEL	string	Уровень логирования (DEBUG, INFO, WARNING, ERROR)	INFO

Разработка

Установка зависимостей для разработки:

pip install -e ".[dev]"

Запуск тестов:

pytest

Проверка кода:

ruff check .

Форматирование кода:

ruff format .

Версия

0.1.0 — Первый релиз с полной функциональностью MCP-сервера.