image-generation-mcp

에이전트에게 그림을 요청하면, base64 덩어리가 아닌 파일 경로를 돌려받습니다. 서버가 Gemini 또는 OpenAI로 이미지를 생성하고, 디스크에 저장한 뒤 절대 경로만 반환합니다. 컨텍스트 창은 깨끗하게 유지되고, 파일은 에이전트가 열거나, 이동하거나, 다른 도구에 넘겨줄 수 있도록 바로 준비되어 있습니다.

기능

• 도구 하나, 절차 없음. generate_image(prompt, images, aspect_ratio) — 이것이 API의 전부입니다.

• 페이로드가 아닌 경로. 절대 파일 경로를 반환하므로 1.5MB PNG가 약 2백만 토큰 대신 약 60토큰만 소모합니다.

• 프로바이더 둘, 자동 선택. 보유한 API 키에 따라 자동으로 선택됩니다. 둘 다 설정했다면? IMAGE_PROVIDER가 결정합니다.

• 이미지 간 변환(Image-to-image). 최대 4개의 참조 이미지를 전달하여 스타일 변경, 편집, 또는 합성이 가능합니다.

• 유연한 입력. 참조 이미지는 로컬 경로, http(s) URL, data: URI, 또는 순수 base64일 수 있습니다 — 서버가 알아서 판별합니다.

• 두 가지 전송 방식. 로컬 클라이언트용 stdio, 포트가 필요할 때 스트리밍 HTTP(localhost 바인딩).

• 정직한 오류. 잘못된 키를 가리는 재시도도, 조용한 프로바이더 폴백도 없습니다. API가 429를 반환하면 429가 표시됩니다.

• 읽을 만큼 작은 코드. 소스 약 540줄, 100줄을 넘는 파일 없음, 전체에 엄격한 타입 적용.

Related MCP server: VisionToolMCP

사전 요구 사항

결제 안내. 이미지 모델은 두 프로바이더 모두 무료 티어가 아닙니다. 결제가 활성화되지 않은 Gemini 키는 모든 이미지 모델에서 429 ... limit: 0을 반환합니다.

빠른 시작

git clone https://github.com/farukcan/image-generation-mcp.git
cd image-generation-mcp
uv sync

cp .env.example .env      # add OPENAI_API_KEY or GEMINI_API_KEY
uv run pytest -m smoke    # generates a real image into out/

마지막 명령은 키가 엔드투엔드로 작동하는지 확인하는 가장 빠른 방법입니다 — 방금 생성한 이미지의 경로를 출력합니다.

에이전트에 추가하기

Claude Code

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

uvx는 첫 실행 시 패키지를 가져와 빌드하고 캐시합니다 — 사전 설치할 것도, 수동으로 업데이트할 것도 없습니다.

편집 가능한 체크아웃이 더 선호되나요? 디렉터리를 가리키면 됩니다:

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uv run --directory /absolute/path/to/image-generation-mcp image-generation-mcp

-s user를 추가하면 이 프로젝트뿐만 아니라 모든 프로젝트에서 사용할 수 있습니다. claude mcp list로 확인하고, claude mcp remove image-generation으로 제거하세요.

Gemini CLI

동일한 플래그, 동일한 형식:

gemini mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

Cursor, Windsurf, Claude Desktop 및 기타

이들은 JSON 구성 파일(.cursor/mcp.json, claude_desktop_config.json, …)을 읽습니다. 항목은 어디서나 동일합니다:

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/farukcan/image-generation-mcp",
        "image-generation-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OUT_DIR": "/absolute/path/where/images/should/land"
      }
    }
  }
}

GUI 클라이언트의 경우 OUT_DIR을 명시적으로 설정하세요 — 예상치 못한 작업 디렉터리로 시작하는 경우가 많아 out/이 엉뚱한 곳에 생성될 수 있습니다.

HTTP 서비스로

uv run image-generation-mcp --transport http --port 8000

http://127.0.0.1:8000/mcp에서 스트리밍 HTTP 엔드포인트를 제공합니다. 루프백에만 바인딩되고 인증이 없으므로, 외부에 노출하기 전에 프록시 뒤에 두세요.

도구

generate_image(prompt: str, images: list[str] | None = None, aspect_ratio: str = "1:1") -> str

작성된 파일의 절대 경로를 반환합니다(예: /path/to/out/20260827-172746-c9b3.png). 파일명은 YYYYmmdd-HHMMSS-xxxx 형식이므로 결과가 시간순으로 정렬되고 충돌하지 않습니다.

종횡비에 관하여: Gemini는 10가지 모두를 지원합니다. OpenAI는 세 가지 크기만 허용하므로, 비율은 가장 가까운 1024x1024, 1536x1024, 또는 1024x1536으로 축소됩니다 — 16:9를 요청하면 3:2가 됩니다.

구성

모든 설정은 환경 변수입니다. 작업 디렉터리(또는 상위 디렉터리)의 .env 파일이 폴백으로 로드되며, 실제 환경 변수가 항상 우선합니다.

API 키 없이 서버를 시작하면 첫 요청에서 찾은 변수 이름을 명시하며 크게 실패합니다.

작동 방식

flowchart LR
    A([MCP client]) -->|generate_image| B[server.py]
    B --> C[aspect.py<br/>validate ratio]
    B --> D[sources.py + download.py<br/>path / URL / base64 → bytes]
    B --> E{"registry.py<br/>which provider?"}
    E -->|GEMINI_API_KEY| F[gemini_provider.py<br/>Interactions API]
    E -->|OPENAI_API_KEY| G[openai_provider.py<br/>generate / edit]
    F --> H[output.py<br/>write into OUT_DIR]
    G --> H
    H -->|absolute path| A

각 모듈은 한 가지 작업만 수행하며 100줄 미만을 유지합니다. 프로바이더는 해석된 구성별로 캐시되므로 SDK 클라이언트와 연결 풀이 요청마다 재구축되는 대신 호출 간에 재사용됩니다.

프로바이더

알아두면 좋은 두 가지 의도적인 특이점:

• Gemini의 이미지 response_format은 명시적 MIME 유형으로 image/jpeg만 허용하므로, 서버는 이를 요청하지 않고 반환되는 형식에 따라 파일 이름을 지정합니다.

• input_fidelity는 OpenAI에 전송되지 않습니다 — gpt-image-2는 이를 400으로 거부하고 자체적으로 높은 충실도를 적용합니다.

개발

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest              # unit tests, all providers mocked
uv run pytest -m smoke -s  # real API calls; costs money, prints the paths

스모크 테스트는 기본적으로 제외되어 일반적인 pytest 실행이 비용을 발생시키지 않습니다. test_edits_a_real_image는 자체 참조 이미지를 만들기 때문에 두 번의 생성 비용이 듭니다.

로고와 스크린샷도 생성된 것입니다 — SVG가 아닌 스크립트를 편집하세요:

uv run python media/generate_logo.py
uv run python media/generate_screenshot.py

파일당 100줄 상한은 우연이 아닌 설계 제약입니다: 모든 모듈을 한 화면에서 검토할 수 있게 유지합니다. 늘리지 말고 분할하세요.

문제 해결

라이선스

MIT © Ömer Faruk Can