Skip to main content
Glama

capped-video-mcp

영상 생성 모델을 에이전트(Claude Code, Claude Desktop 등)에서 부르는 로컬 MCP 서버. 생성은 Replicate와 fal을 통해 호출하고, API 키는 각자 자기 것을 쓴다.

지원 모델: seedance-2.5(Replicate, 기본), seedance-2.5-fal, kling-3.0, wan-2.5, veo-3.1-fast, veo-3.1-lite, hailuo-2.3, gemini-omni-1.2-flash. 모델마다 허용 길이·해상도·가격이 다르다(list_models 또는 기본 config.toml).

비용 상한(모델 허용 목록, 해상도·길이, 일일·월간 예산, 동시 작업 수)과 자동 다운로드를 서버가 강제한다.

알파 단계. 가격표는 서버가 예산을 계산하는 예상값이다(제공처 공시가 기준, 2026-11-22 확인). 실제 청구액은 Replicate·fal 대시보드에서 확인한다. 제공처 API 입력 형식은 공개 스키마와 대조했지만, 실제 생성→다운로드까지의 종단 검증은 아직 진행 중이다. 처음에는 가장 싼 조건(480p 4~5초)으로 시험하고 예산 상한을 낮게 두길 권한다.

설치와 등록

필요한 것: uv, Replicate 토큰 또는 fal 키 (둘 중 하나만 있어도 된다. 키가 없는 쪽 모델은 꺼진다). 선택: ffmpeg (결과 미리보기 preview_video에만 쓴다).

Claude Code

claude mcp add capped-video --scope user \
  -e FAL_KEY=fal-xxxx \
  -e REPLICATE_API_TOKEN=r8_xxxx \
  -e CAPPED_VIDEO_DEFAULT_MODEL=kling-3.0 \
  -e CAPPED_VIDEO_DAILY_MAX_USD=3 \
  -- uvx capped-video-mcp

--scope user는 모든 프로젝트에서 쓴다. 팀 저장소에 .mcp.json으로 공유할 때는 키를 적지 말고 각자의 환경 변수를 참조한다.

{
  "mcpServers": {
    "capped-video": {
      "command": "uvx",
      "args": ["capped-video-mcp"],
      "env": {
        "FAL_KEY": "${FAL_KEY:-}",
        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN:-}",
        "CAPPED_VIDEO_DEFAULT_MODEL": "kling-3.0"
      }
    }
  }
}

/mcp로 연결을 확인한다. generate_video는 과금되므로 자동 허용 목록에 넣지 말고 매번 승인하는 것을 권한다.

uvx는 한 번 받은 버전을 계속 쓴다. 새 버전으로 바꾸려면 uvx capped-video-mcp@latest로 등록하거나 uvx --refresh capped-video-mcp를 한 번 실행한다.

Claude Desktop 등 다른 클라이언트

claude_desktop_config.json(또는 각 클라이언트의 MCP 설정)의 mcpServers에 위 JSON과 같은 형식으로 넣는다. 키는 ${...} 대신 값을 직접 쓴다.

키 없이 시험

CAPPED_VIDEO_PROVIDER=mock을 함께 넘기면 실제 API를 부르지 않고 가짜 파일을 만든다. 기록도 실제와 분리된다(data/usage-mock.json, <출력 폴더>/mock/).

Related MCP server: longtake-mcp

도구

도구

과금

하는 일

generate_video

예

생성 작업을 만들고 job_id를 돌려준다. model, resolution, duration_sec, aspect_ratio를 요청마다 고를 수 있다. 최근 10분 안의 같은 요청은 새 작업을 만들지 않고 기존 job_id를 duplicate: true로 돌려준다(과금 없음). request_id로도 중복을 잡고, 같은 영상을 하나 더 원할 때만 force: true

get_video_status

아니오

상태 확인. 최대 60초 기다린다. 완료면 파일 경로

download_video

아니오

자동 다운로드가 실패했을 때 다시 시도

get_usage

아니오

오늘·이번 달 사용량과 상한

estimate_video

아니오

조건(길이·해상도·비율)에 맞는 모델별 예상 비용을 싼 순서로, 남은 예산과 함께. 예산 안에서 가장 싼 모델(cheapest), 조건을 못 맞추는 모델과 이유(unavailable), 최근 같은 요청(duplicate_of)

preview_video

아니오

완성된 영상의 프레임 6장을 한 이미지로 붙여 이미지로 돌려준다. 에이전트가 결과를 보고 재생성 여부를 판단할 수 있다. ffmpeg 필요(없으면 이유를 돌려줌)

list_models

아니오

허용 모델, 가격, 길이 범위, 현재 기본값

결과 수거는 서버(클라이언트 세션)가 켜져 있는 동안에만 일어난다. 생성 중에는 세션을 닫지 않는다.

중복 요청 감지

에이전트는 응답이 늦거나 애매하면 같은 요청을 다시 보내기 쉽다. 서버는 프롬프트(앞뒤·연속 공백만 정리)·모델·해상도·길이·화면 비율이 같은 요청이 duplicate_window_minutes(기본 10분) 안에 다시 오면 제공처를 부르지 않고 기존 작업의 상태를 돌려준다. 과금되지 않은 거부(create_failed)와 확정 실패(failed)는 다시 시도할 수 있으므로 중복으로 보지 않는다. 검사와 예약이 같은 파일 잠금 안에서 일어나서 두 클라이언트가 동시에 같은 요청을 보내도 하나만 만들어진다. CAPPED_VIDEO_DUPLICATE_WINDOW_MINUTES=0으로 끌 수 있다.

생성 전 비용 확인 (선택)

CAPPED_VIDEO_CONFIRM_ABOVE_USD=0.5처럼 임계값을 주면, 예상 비용이 그 이상일 때 서버가 클라이언트에 "약 $0.63이 과금됩니다. 진행할까요?"를 직접 묻는다(MCP elicitation). 클라이언트의 도구 승인 설정과 무관하게 동작하므로, 자동 승인 모드에서도 비싼 생성은 한 번 더 확인받을 수 있다. 클라이언트가 이 요청을 지원하지 않으면 CAPPED_VIDEO_CONFIRM_FALLBACK(allow 기본: 그냥 진행, deny: 거부)을 따른다. 기본값 0은 묻지 않는다.

제공처 전환

같은 모델이 두 제공처에 있으면(seedance-2.5 ↔ seedance-2.5-fal) 1차 제공처가 요청을 확정 거부(4xx, 점검 등)했을 때 남은 예산을 다시 확인하고 대체 모델로 만든다. 응답에 failover_from이 붙는다. 결과를 알 수 없는 오류(타임아웃, 5xx)에서는 과금됐을 수 있으므로 전환하지 않는다. CAPPED_VIDEO_FAILOVER=false로 끈다. 대체 모델은 설정의 fallback_model로 바꿀 수 있다.

결과 미리보기

preview_video는 ffmpeg로 프레임 6장(가로 3장 × 2줄, 시간 순서)을 한 JPEG로 붙여 이미지 콘텐츠로 돌려준다. 결과는 영상 옆에 <job_id>.preview.jpg로 저장해 다시 만들지 않는다. ffmpeg는 PATH 또는 CAPPED_VIDEO_FFMPEG로 찾고, 없으면 영상 경로와 함께 이유만 돌려준다. 장수·가로 크기는 설정 [preview]에서 바꾼다.

설정

설정은 아래 순서로 덮어쓴다. 뒤에 있는 것이 이긴다.

  1. 패키지 기본값 src/capped_video_mcp/config.toml

  2. 데이터 폴더의 config.toml (있으면. 바꿀 항목만 쓴다)

  3. CAPPED_VIDEO_* 환경 변수 (등록 때 -e/env로 넘기거나 데이터 폴더의 .env)

환경 변수

변수

설정 위치

예

FAL_KEY

fal API 키 (API 범위, ADMIN 범위 쓰지 않기)

REPLICATE_API_TOKEN

Replicate 토큰

CAPPED_VIDEO_DEFAULT_MODEL

defaults.model

kling-3.0

CAPPED_VIDEO_DEFAULT_RESOLUTION

defaults.resolution

480p

CAPPED_VIDEO_DEFAULT_DURATION_SEC

defaults.duration_sec

5

CAPPED_VIDEO_DEFAULT_ASPECT_RATIO

defaults.aspect_ratio

9:16

CAPPED_VIDEO_MAX_RESOLUTION

limits.max_resolution

720p

CAPPED_VIDEO_MAX_DURATION_SEC

limits.max_duration_sec

10

CAPPED_VIDEO_DAILY_MAX_COUNT

limits.daily_max_count

10

CAPPED_VIDEO_DAILY_MAX_USD

limits.daily_max_usd

5

CAPPED_VIDEO_MONTHLY_MAX_USD

limits.monthly_max_usd

30

CAPPED_VIDEO_MAX_PENDING_JOBS

limits.max_pending_jobs

3

CAPPED_VIDEO_DUPLICATE_WINDOW_MINUTES

limits.duplicate_window_minutes (같은 요청을 중복으로 보는 시간. 0이면 끔)

10

CAPPED_VIDEO_CONFIRM_ABOVE_USD

limits.confirm_above_usd (이 금액 이상이면 생성 전 사용자 확인. 0이면 끔)

0.5

CAPPED_VIDEO_CONFIRM_FALLBACK

limits.confirm_fallback (확인을 지원하지 않는 클라이언트: allow/deny)

allow

CAPPED_VIDEO_FAILOVER

limits.failover (확정 거부 시 fallback_model로 전환)

true

CAPPED_VIDEO_FFMPEG

preview.ffmpeg (미리보기용 ffmpeg 경로. 비우면 PATH)

C:/ffmpeg/bin/ffmpeg.exe

CAPPED_VIDEO_OUTPUT_DIR

download.dir (영상 저장 폴더. 상대 경로면 데이터 폴더 기준)

~/Videos/capped-video

CAPPED_VIDEO_HOME

데이터 폴더 위치. 절대 경로, 등록 env로만 (.env에 쓰면 효과 없음)

D:/capped-video

CAPPED_VIDEO_PROVIDER

mock이면 실제 API를 부르지 않는다. 다른 값은 오류

mock

빈 값은 없는 것으로 본다(.env에 값이 있으면 그 값을 쓴다). 값이 잘못되면(없는 모델, 모르는 해상도, 숫자가 아닌 예산 등) 서버가 뜨지 않고 어떤 변수·파일이 문제인지 알려 준다. 경로에는 ~와 환경 변수(%USERPROFILE%, $HOME)를 쓸 수 있다. API 키를 도구 인자나 대화로 넘기지 않는다(대화 기록과 로그에 남는다).

데이터 폴더

실행 방식

위치

CAPPED_VIDEO_HOME 지정

그 폴더

uvx·pip 설치

~/.capped-video-mcp (Windows: C:\Users\<이름>\.capped-video-mcp)

이 저장소에서 uv sync 후 실행

저장소 루트

안에 생기는 것: config.toml·.env(선택, 직접 만든다), output/(영상), data/usage.json(사용량 기록), logs/.

데이터 폴더 config.toml 예. 표([limits] 등)는 쓴 키만 바뀌고, 목록([[models]], allowed_hosts)은 통째로 바뀐다.

[defaults]
model = "veo-3.1-lite"

[limits]
daily_max_usd = 2.0

[download]
dir = 'D:\Videos\capped-video'   # Windows 경로는 작은따옴표 또는 / 로 쓴다

개발

uv sync
cp .env.example .env        # 키를 채운다. 키 없이 시험하려면 CAPPED_VIDEO_PROVIDER=mock
uv run pytest               # 실제 API 를 부르지 않는다

저장소에서 띄우려면 .mcp.json(git 제외)에 등록한다.

{
  "mcpServers": {
    "capped-video": {
      "command": "uv",
      "args": ["run", "--directory", "<저장소 경로>", "python", "-m", "capped_video_mcp"]
    }
  }
}

배포 절차는 doc/배포가이드.md, 작업 경과는 doc/작업진행.md에 있다.

라이선스

MIT


공식 MCP Registry 등록 이름 (PyPI 패키지 소유 확인용 표식):

mcp-name: io.github.bslim1009/capped-video-mcp

Available Tools

7 tools
download_videoA
Idempotent

내려받지 못한(lost) 작업의 다운로드를 다시 시도하거나, 완료된 파일 경로를 돌려준다. 과금되지 않는다.

보통은 서버가 자동으로 내려받으므로 부를 필요가 없다. URL 이나 경로는 받지 않는다.

Inputs: job_id (required), wait_seconds. Returns: object

estimate_videoA
Read-only

과금 없이 비용을 견적한다. 조건(길이·해상도·화면 비율)에 맞는 모델을 싼 순서로, 남은 예산과 함께 돌려준다.

    generate_video 를 부르기 전에 모델을 고르거나 예산이 충분한지 볼 때 쓴다. cheapest 는 예산 안에서 가장 싼 모델.
    조건을 지정하지 않으면 모델별 가장 싼 값을 가정한다. 조건을 만족하지 못하는 모델은 unavailable 에 이유와 함께 나온다.
    prompt 를 주면 같은 요청이 최근에 있었는지(duplicate_of)도 알려 준다.
    

Inputs: model, prompt, resolution, aspect_ratio, +1 more. Returns: object

generate_videoA

영상 생성 작업을 만든다. 과금된다. 사용자가 영상 생성을 요청했을 때만 부른다.

    기본값: config.toml 의 defaults (seedance-2.5 / Replicate, 480p, 5초, 16:9).
    모델마다 허용 해상도·길이·화면 비율과 가격이 다르다. 다른 모델을 쓰기 전에 list_models 로 확인한다
    (예: veo 는 4·6·8초, wan 은 5·10초, hailuo 는 6·10초만). 지정하지 않으면 모델에 맞는 가장 싼 값을 고른다.
    자동 길이는 허용하지 않는다. 일일·월간 예산을 넘으면 거부한다.
    job_id 를 반환한다. 완료되면 서버가 출력 폴더에 자동 저장하며, get_video_status 로 확인한다.
    오류가 "다시 보내지 마세요"라고 하면 같은 요청을 반복하지 않는다.
    같은 요청(프롬프트·모델·해상도·길이·비율)이 최근에 이미 접수됐으면 새 작업을 만들지 않고 기존 job_id 를
    duplicate=true 로 돌려준다 (과금 없음). request_id 를 주면 그 값으로도 중복을 잡는다.
    사용자가 같은 영상을 하나 더 원할 때만 force=true 를 쓴다.
    1차 제공처가 요청을 확정 거부하면 대체 모델로 만들고 failover_from 에 원래 모델을 적는다.
    예상 비용이 설정 임계값 이상이면 서버가 사용자에게 직접 확인을 요청할 수 있다.
    

Inputs: prompt (required), force, model, request_id, +3 more. Returns: object

get_usageA
Read-only

오늘·이번 달 생성 횟수와 예상 비용, 상한, 진행 중인 작업 수를 돌려준다.

Inputs: no named parameters. Returns: object

get_video_statusA
Read-only

작업 상태를 확인한다. 과금되지 않는다.

    완료될 때까지 최대 wait_seconds(상한 60초) 동안 기다린다.
    status 가 queued/running/downloading 이면 이 도구를 다시 부른다.
    succeeded 이면 file 에 저장된 영상 경로가 있다.
    

Inputs: job_id (required), wait_seconds. Returns: object

list_modelsA
Read-only

사용할 수 있는 모델, 해상도별 초당 가격(USD), 길이 범위, 기본값을 돌려준다.

Inputs: no named parameters. Returns: object

preview_videoA
Read-only

완성된 영상의 프레임 여러 장을 한 이미지로 붙여 돌려준다. 과금되지 않는다.

    영상을 직접 볼 수 없으니 이 이미지로 결과가 요청과 맞는지 확인한다. 왼쪽 위부터 오른쪽 아래로 시간 순서다.
    succeeded 상태에서만 만들 수 있다. ffmpeg 가 없으면 preview_available=false 와 이유를 돌려준다.
    

Inputs: job_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct lifecycle stage: pricing (estimate_video/list_models), creation (generate_video), polling (get_video_status), recovery (download_video), inspection (preview_video), and budget (get_usage). The descriptions explicitly state when NOT to call a tool (download_video: 'usually unnecessary'; generate_video: only when user requests creation), which removes the main overlap risk. The paid-vs-free distinction is stated on every tool.

    Naming Consistency5/5

    All names follow a consistent snake_case verb_noun pattern: generate_video, estimate_video, preview_video, download_video, list_models, get_usage, get_video_status. The only minor variation is the three-part get_video_status, which still fits the scheme.

    Tool Count5/5

    Seven tools map cleanly onto one domain (generate, check, fetch, preview, price, list, budget) with no filler. Each tool earns its place, and none could be merged without losing a distinct paid/free or blocking/non-blocking behavior.

    Completeness4/5

    The generation lifecycle is well covered: model discovery, cost estimation, creation, polling, recovery download, preview, and budget tracking. Missing operations are cancel/abort for an in-flight paid job and a list of past jobs; today an agent must retain job_ids itself, though this is a workable gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create and manage AI video productions through Longtake Studio using their own API keys, including casting characters, shooting takes on models such as Seedance, Veo, Gemini Omni, and Kling, drafting and finishing in 1080p, and tracking render costs.
      74 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to generate ByteDance Seedance videos and Seedream images through a BytePlus key, pricing every request in dollars before it is sent. It adds budget limits, ask-first approvals and whole-key spend tracking so costly generations cannot happen without consent.
      9
      MIT