gemini-media-mcp

Google Gemini API 및 Vertex AI를 통한 AI 미디어 생성을 위한 통합 Go MCP 서버.

기능

• 이미지 생성 -- 구성 가능한 가로세로 비율 및 해상도(1K/2K/4K)를 지원하는 텍스트-이미지 변환

• 이미지 편집 -- 자연어 프롬프트를 사용하여 기존 이미지 수정

• 다중 참조 구성 -- 스타일/콘텐츠 가이드를 사용하여 최대 3개의 참조 이미지 결합

• 비디오 생성 -- Veo 3.1 Lite, Fast 및 Standard 티어를 통한 텍스트-비디오 변환

• 이미지-비디오 변환 -- 정지 이미지를 비디오 클립으로 애니메이션화

• 비디오 확장 -- 더 긴 콘텐츠를 위해 클립 연결(Fast 및 Standard 티어)

• 텍스트-음성 변환(TTS) -- 구성 가능한 음성과 언어로 음성 오디오 생성

• 음악 생성 -- Lyria 3를 통한 AI 음악(30초 클립 또는 보컬이 포함된 전체 곡, 구조 제어)

• 단일 바이너리 -- 런타임 종속성 없음, stdio 전송을 통해 실행

• 공급자 추상화 -- 이미지, 비디오, 오디오 및 모델 작업을 위한 백엔드 독립적 인터페이스

• 듀얼 백엔드 -- Gemini API(API 키) 및 Vertex AI(프로젝트 자격 증명) 모두 지원

빠른 시작

# Install
go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest

# Configure (Gemini API; either variable name works)
export GEMINI_API_KEY="your-api-key"
# export GOOGLE_API_KEY="your-api-key"

# Or configure (Vertex AI)
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# Run directly (stdio transport)
gemini-media-mcp

그런 다음 MCP 클라이언트에 추가하십시오. 아래의 MCP 클라이언트 구성을 참조하십시오.

구성

*GOOGLE_API_KEY 또는 GOOGLE_CLOUD_PROJECT 중 하나는 반드시 설정해야 합니다. 둘 다 설정된 경우 API 키가 우선합니다(다른 도구를 위해 셸에서 GOOGLE_CLOUD_PROJECT가 설정된 경우 충돌 방지).

어떤 백엔드가 활성화되어 있는지 확실하지 않은 경우, MCP 클라이언트에서 get_config를 호출하여 선택된 백엔드와 출력 디렉토리를 확인하십시오.

사용 가능한 도구

비동기 도구는 작업 ID를 즉시 반환합니다. video_status를 사용하여 완료 여부를 폴링한 다음 download_video를 사용하여 파일을 검색하십시오.

모델 티어

이미지

두 티어 모두 1K, 2K, 4K 해상도와 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 가로세로 비율을 지원합니다.

비디오

지원되는 가로세로 비율은 16:9 및 9:16입니다. 지원되는 길이는 4, 6, 8초입니다. Lite는 720p 및 1080p를 지원합니다. Fast 및 Standard는 720p, 1080p 및 4K를 지원합니다. 비디오 확장(extend_video)은 Fast 및 Standard 티어에서만 사용할 수 있으며, 확장 티어는 원래 생성 티어와 일치해야 합니다.

오디오 (TTS)

generate_audio 도구는 텍스트를 음성 오디오로 변환합니다. 다음을 지원합니다:

• 음성 선택 -- Aoede, Kore, Puck 등과 같은 사전 구축된 음성 중에서 선택. 기본값: Aoede

• 언어 -- 언어 코드 설정(예: en-US, it-IT, cs-CZ, de-DE). 기본값: en-US

• 자연스러운 음성 -- 적절한 속도와 억양으로 표현력이 풍부하고 자연스러운 음성 생성

출력은 원시 PCM 오디오(audio/L16, 24kHz 샘플링 레이트)로 저장됩니다. 이 파일은 ffplay와 같은 도구로 재생하거나 다른 형식으로 변환할 수 있습니다:

# Play directly
ffplay -f s16le -ar 24000 -ac 1 ~/generated_media/audio-2026-04-02T12-20-12-0603.pcm

# Convert to WAV
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.wav

# Convert to MP3
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.mp3

음악 (Lyria)

generate_music 도구는 텍스트 설명에서 AI 생성 음악을 만듭니다. 기능은 다음과 같습니다:

• 장르 및 스타일 -- 장르, 악기, BPM, 키/스케일, 분위기 지정

• 구조 제어 -- [Verse], [Chorus], [Bridge], [Intro], [Outro]와 같은 태그 사용

• 사용자 지정 가사 -- 보컬 트랙을 위한 섹션 마커가 포함된 가사 포함

• 타임스탬프 제어 -- 정확한 섹션 타이밍을 위한 [0:00 - 0:10] Intro: gentle piano... 사용

• 다국어 -- 프롬프트 언어가 출력 언어를 결정

• 고충실도 -- 48kHz 스테레오 MP3 출력

생성된 모든 음악에는 SynthID 워터마크가 표시됩니다.

프롬프트 예시:

# Instrumental
"A gentle acoustic guitar melody in C major, 90 BPM, calm and peaceful indie folk"

# With structure
"[Intro] Ambient synth pad, ethereal
[Verse] Lo-fi hip-hop beat, mellow piano chords, vinyl crackle
[Chorus] Uplifting, add strings and gentle drums
[Outro] Fade out with reverb"

# With lyrics
"Upbeat pop song, 120 BPM, major key
[Chorus] We're dancing in the light / Everything feels right / Under stars so bright tonight"

티어 이름(lite, fast, standard, nb2, pro, tts, clip, full) 또는 원시 모델 ID를 직접 전달할 수 있습니다.

MCP 클라이언트 구성

Claude Code

Claude Code MCP 설정(~/.claude/settings.json 또는 프로젝트 .mcp.json)에 추가하십시오:

{
  "mcpServers": {
    "gemini-media": {
      "command": "gemini-media-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "MEDIA_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

위의 env 블록에서 GOOGLE_API_KEY 또는 GEMINI_API_KEY를 사용하십시오. 둘 다 허용됩니다.

또는 소스에서 빌드하는 경우:

{
  "mcpServers": {
    "gemini-media": {
      "command": "/path/to/gemini-media-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code를 위한 동반 기술

skills/ 디렉토리에는 MCP 도구 위에서 대화형 워크플로우를 제공하는 Claude Code 기술이 포함되어 있습니다. 각 기술은 특정 미디어 유형에 대한 프롬프트 엔지니어링, 모델 선택 및 반복적인 개선 과정을 통해 Claude를 안내합니다.

기술을 설치하려면 해당 디렉토리를 ~/.claude/skills/로 복사하십시오:

cp -r skills/video-gen ~/.claude/skills/
cp -r skills/music-gen ~/.claude/skills/
cp -r skills/tts-gen ~/.claude/skills/
cp -r skills/gemini-image-gen ~/.claude/skills/

기술은 선택 사항입니다. MCP 도구는 기술 없이도 작동합니다. 하지만 기술은 프롬프트 엔지니어링 가이드, 모델 티어 권장 사항 및 출력 품질을 크게 향상시키는 대화형 검토 워크플로우를 추가합니다.

소스에서 빌드

git clone https://github.com/mordor-forge/gemini-media-mcp.git
cd gemini-media-mcp
go build ./cmd/gemini-media-mcp/

바이너리는 ./gemini-media-mcp에 생성됩니다.

테스트를 실행하려면:

go test ./...

기여

1. 저장소 포크

2. 기능 브랜치 생성 (git checkout -b feature/your-feature)

3. 변경 사항을 적용하고 테스트 추가

4. go test ./... 및 go vet ./... 실행

5. 변경 사항 커밋

6. main 브랜치에 대한 풀 리퀘스트 열기

라이선스

Apache-2.0