capped-video-mcp
Used as one of the two video-generation backends: the server submits generation jobs to Replicate for its supported models (e.g. seedance-2.5, default), polls job status, and automatically downloads the finished videos. Replicate is also the failover counterpart for the equivalent fal model, and its pricing is used to compute per-request cost estimates against the configured daily/monthly budget caps.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@capped-video-mcp estimate a 5s 480p video, then generate the cheapest one"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
도구
도구 | 과금 | 하는 일 |
| 예 | 생성 작업을 만들고 |
| 아니오 | 상태 확인. 최대 60초 기다린다. 완료면 파일 경로 |
| 아니오 | 자동 다운로드가 실패했을 때 다시 시도 |
| 아니오 | 오늘·이번 달 사용량과 상한 |
| 아니오 | 조건(길이·해상도·비율)에 맞는 모델별 예상 비용을 싼 순서로, 남은 예산과 함께. 예산 안에서 가장 싼 모델( |
| 아니오 | 완성된 영상의 프레임 6장을 한 이미지로 붙여 이미지로 돌려준다. 에이전트가 결과를 보고 재생성 여부를 판단할 수 있다. ffmpeg 필요(없으면 이유를 돌려줌) |
| 아니오 | 허용 모델, 가격, 길이 범위, 현재 기본값 |
결과 수거는 서버(클라이언트 세션)가 켜져 있는 동안에만 일어난다. 생성 중에는 세션을 닫지 않는다.
중복 요청 감지
에이전트는 응답이 늦거나 애매하면 같은 요청을 다시 보내기 쉽다. 서버는 프롬프트(앞뒤·연속 공백만 정리)·모델·해상도·길이·화면 비율이 같은 요청이 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]에서 바꾼다.
설정
설정은 아래 순서로 덮어쓴다. 뒤에 있는 것이 이긴다.
패키지 기본값 src/capped_video_mcp/config.toml
데이터 폴더의
config.toml(있으면. 바꿀 항목만 쓴다)CAPPED_VIDEO_*환경 변수 (등록 때-e/env로 넘기거나 데이터 폴더의.env)
환경 변수
변수 | 설정 위치 | 예 |
| fal API 키 (API 범위, ADMIN 범위 쓰지 않기) | |
| Replicate 토큰 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 데이터 폴더 위치. 절대 경로, 등록 env로만 ( |
|
|
|
|
빈 값은 없는 것으로 본다(.env에 값이 있으면 그 값을 쓴다). 값이 잘못되면(없는 모델, 모르는 해상도, 숫자가 아닌 예산 등) 서버가 뜨지 않고 어떤 변수·파일이 문제인지 알려 준다. 경로에는 ~와 환경 변수(%USERPROFILE%, $HOME)를 쓸 수 있다. API 키를 도구 인자나 대화로 넘기지 않는다(대화 기록과 로그에 남는다).
데이터 폴더
실행 방식 | 위치 |
| 그 폴더 |
|
|
이 저장소에서 | 저장소 루트 |
안에 생기는 것: 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 toolsdownload_videoAIdempotent
내려받지 못한(lost) 작업의 다운로드를 다시 시도하거나, 완료된 파일 경로를 돌려준다. 과금되지 않는다.
보통은 서버가 자동으로 내려받으므로 부를 필요가 없다. URL 이나 경로는 받지 않는다.
Inputs: job_id (required), wait_seconds. Returns: object
estimate_videoARead-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_usageARead-only
오늘·이번 달 생성 횟수와 예상 비용, 상한, 진행 중인 작업 수를 돌려준다.
Inputs: no named parameters. Returns: object
get_video_statusARead-only
작업 상태를 확인한다. 과금되지 않는다.
완료될 때까지 최대 wait_seconds(상한 60초) 동안 기다린다.
status 가 queued/running/downloading 이면 이 도구를 다시 부른다.
succeeded 이면 file 에 저장된 영상 경로가 있다.
Inputs: job_id (required), wait_seconds. Returns: object
list_modelsARead-only
사용할 수 있는 모델, 해상도별 초당 가격(USD), 길이 범위, 기본값을 돌려준다.
Inputs: no named parameters. Returns: object
preview_videoARead-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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Generate reproducible image, video, and audio assets with leading models and your own provider keys.
Generate video and images with prepaid USD billing and explicit per-job spending limits.
Video tools for agents (trim, captions, 9:16, GIF/MP3) + hire us for fixed-price jobs. No API key.
Create images & video from any MCP agent — 17 models, spend limits, one URL.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to generate, manage, and download AI-generated videos using OpenAI's Sora models, supporting text prompts, image-to-video, remixing, and more.9MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npm1MIT
- AlicenseAqualityCmaintenanceEnables 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.9MIT
- AlicenseAqualityCmaintenanceEnables Claude to generate videos from text prompts via the Replicate API, check generation status, and download completed videos to disk.3MIT