@ffmpeg-micro/mcp-server

AI 에이전트 — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code 및 기타 모든 MCP 호환 클라이언트 —가 FFmpeg Micro REST API를 통해 비디오 트랜스코딩 작업을 생성, 모니터링, 다운로드할 수 있게 해주는 Model Context Protocol 서버입니다.

기능 소개

FFmpeg Micro 퍼블릭 API에 대응하는 도구를 노출합니다:

블루프린트

블루프린트는 POST /v1/blueprints/{slug}/runs 뒤에 있는 사전 구축된 워크플로입니다. 도구 설명에 각 블루프린트의 입력 필드가 문서화되어 있습니다. 참고:

• 대부분의 블루프린트는 FFmpeg 레인에서 실행되며 플랜 컴퓨팅 시간(분)으로 계산됩니다(토큰 없음). 생성형 블루프린트(product-ad)는 토큰을 차감하며, 402 insufficient_tokens 응답은 계정에 토큰 팩이 필요함을 의미합니다 (대시보드).

• caption-video는 대본(srt_text)과 함께 awaiting_review 상태로 일시 중지되어 에이전트가 렌더링 전에 검토/편집할 수 있습니다. continue_blueprint_run으로 재개합니다.

• 다중 출력 블루프린트(listing-kit, hook-variants)는 {label, url}의 outputs 배열을 반환합니다. 존재하는 경우 output_url보다 이를 사용하세요.

• 출력 URL은 10분 TTL로 서명됩니다. 새 링크가 필요하면 실행을 다시 가져오세요.

로컬 파일 업로드

request_upload_url + confirm_upload 쌍을 사용하면 MCP 호스트가 원시 API 키나 gs:// URL을 직접 다루지 않고도 로컬 파일을 FFmpeg Micro 스토리지 버킷에 업로드할 수 있습니다:

1. 호스트가 {filename, contentType, fileSize}로 request_upload_url을 호출합니다 → 단기 유효한 사전 서명된 HTTPS URL을 받습니다.

2. 호스트는 동일한 Content-Type으로 파일 바이트를 해당 URL에 PUT합니다.

3. 호스트가 {filename: <1단계의 스토리지 파일명>, fileSize}로 confirm_upload를 호출합니다 → 최종 gs://... fileUrl을 받습니다.

4. 호스트는 해당 fileUrl을 transcribe_audio / transcode_video / transcode_and_wait에 전달합니다.

Related MCP server: Rendi MCP Server

빠른 시작

이 내용을 프로젝트의 .mcp.json(또는 MCP 클라이언트 설정)에 추가하세요:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

끝입니다. AI 도구가 처음 연결하면 브라우저 창이 열려 OAuth를 통해 FFmpeg Micro 계정으로 로그인하게 됩니다. 승인하면 토큰이 캐시되어 다시 요청되지 않습니다.

복사할 API 키도, 설정할 환경 변수도 없습니다.

인증

OAuth (권장)

MCP 서버는 PKCE 및 동적 클라이언트 등록을 사용하는 OAuth 2.1을 지원합니다. MCP 클라이언트가 전체 흐름을 자동으로 처리합니다:

1. 클라이언트가 /.well-known/oauth-authorization-server를 통해 OAuth 엔드포인트를 검색합니다

2. 클라이언트가 동적으로 자신을 등록합니다

3. 브라우저가 열려 로그인하고 액세스를 승인합니다

4. 토큰이 교환되어 캐시됩니다 — 이후 연결은 즉시 이루어집니다

위 설정을 headers 또는 env 블록 없이 사용하면 이것이 기본값입니다.

API 키 (대안)

API 키를 직접 사용하려는 경우(예: 자동화 또는 CI), Bearer 토큰으로 전달할 수 있습니다:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

API 키는 대시보드에서 받을 수 있습니다.

stdio (로컬 설치)

npx를 사용하여 서버를 로컬 프로세스로 실행합니다. Node.js 22.14 이상이 필요합니다.

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npx -y는 매번 최신 버전을 가져옵니다. stdio 서버를 지원하는 모든 MCP 클라이언트가 이 설정으로 작동합니다.

호환 도구

HTTP 설정(OAuth)은 streamable HTTP 전송을 지원하는 모든 MCP 클라이언트에서 작동합니다:

• Claude Code (CLI)

• Claude Desktop

• Cursor

• Windsurf

• VS Code (GitHub Copilot MCP)

stdio 설정은 stdio 전송을 지원하는 모든 MCP 클라이언트에서 작동합니다.

예시 프롬프트

연결되면 다음과 같은 요청을 할 수 있습니다:

• "이 비디오를 720p MP4로 트랜스코딩하고 완료되면 다운로드 URL을 알려줘."

• "이 가로형 비디오를 정사각형으로 크롭해 줘."

• "내 비디오에 'Episode 12'라는 텍스트 오버레이를 추가해 줘."

• "이번 주 실패한 작업을 나열해 줘."

• "b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3 작업을 취소해 줘."

개발

git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh

setup.sh가 의존성을 설치하고, 빌드하고, git 훅을 연결합니다.

반복 작업을 위해 MCP 클라이언트가 로컬 빌드를 가리키게 하세요:

{
  "mcpServers": {
    "ffmpeg-micro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
      "env": { "FFMPEG_MICRO_API_KEY": "…" }
    }
  }
}

MCP Inspector는 도구 스키마와 응답을 반복 작업하는 가장 빠른 방법입니다:

npx @modelcontextprotocol/inspector node dist/index.js

로컬 API 게이트웨이를 대상으로 HTTP 서버를 로컬에서 실행하려면:

FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serve

로컬에서 통합 테스트 실행

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

통합 테스트는 실제 FFmpeg Micro 프로덕션 API를 대상으로 합니다. 읽기 전용입니다(작업이 생성되지 않음).

업로드 도구 엔드 투 엔드 스모크 테스트

단위 테스트는 모의(mocked) fetch를 사용하므로 도구 등록 + Zod 스키마 + URL 경로는 검증하지만, 와이어 형태가 게이트웨이가 실제로 반환하는 것과 일치하는지는 검증하지 않습니다. 두 개의 스모크 스크립트는 실제 API 키를 사용하여 실제 MCP 서버를 대상으로 전체 request_upload_url → PUT → confirm_upload 흐름을 실행합니다. 순서대로 실행하세요 — 먼저 stdio(가장 빠른 신호), 그 다음 병합 전/후에 배포된 HTTP 서버 순입니다:

# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>

# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
  node scripts/smoke-upload-http.mjs <local-file>

두 스크립트 모두 기본적으로 프로덕션 API를 호출하며 과금 대상 시간(분)을 소비합니다(stdio 스크립트는 엔드 투 엔드 확인을 위해 transcribe_audio로 연결됩니다). 15-second.mp3 같은 작은 파일을 전달하면 비용을 무시할 수 있는 수준으로 유지할 수 있습니다.

세 번째 스크립트는 블루프린트 도구를 스모크 테스트합니다(resize-format에서 run_blueprint + get_blueprint_run을 완료될 때까지 폴링한 다음, 다중 출력을 테스트하기 위해 hook-variants에서 run_blueprint_and_wait 실행). FFmpeg 레인 블루프린트만 사용하므로 플랜 컴퓨팅 시간은 소비하지만 토큰은 사용하지 않습니다:

npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs

보호(protection)가 적용된 Vercel 프리뷰 접근

Vercel 프리뷰 배포는 기본적으로 Deployment Protection으로 보호됩니다. 프리뷰 URL을 대상으로 HTTP 스모크 스크립트를 실행하려면 프로젝트의 Vercel 설정에서 Protection-Bypass-for-Automation 토큰을 생성하고 VERCEL_BYPASS로 전달하세요:

FFMPEG_MICRO_API_KEY=your_key \
  MCP_URL=https://your-preview.vercel.app/ \
  VERCEL_BYPASS=your_bypass_token \
  node scripts/smoke-upload-http.mjs <local-file>

스크립트는 모든 요청에 x-vercel-protection-bypass 헤더로 토큰을 전송합니다. x-vercel-set-bypass-cookie: true는 전송하지 않습니다 — 해당 변형은 POST 시 307 쿠키 설정 리다이렉트를 유발하며, MCP SDK의 StreamableHTTPClientTransport는 이를 따르지 않아 요청이 실패합니다. 헤더만 사용하면 리다이렉트 과정 없이 200이 직접 반환됩니다.

릴리스 프로세스

릴리스는 trusted publishing을 통해 npm에 게시되고, ffmpeg-micro.com의 Ed25519 DNS TXT 레코드로 인증되어 MCP Registry에는 com.ffmpeg-micro/mcp-server로 게시됩니다. 해당 개인 키는 MCP_PRIVATE_KEY GitHub Actions 시크릿에 저장됩니다. npm 쪽은 OIDC trusted publishing을 사용하므로 npm 토큰이 저장되지 않습니다.

릴리스는 Changesets를 통해 자동화됩니다. 기여자는 버전을 수동으로 올리거나 커밋에 태그를 달거나 게시 명령을 실행하지 않습니다 — PR에 changeset을 첨부하면 릴리스 파이프라인이 나머지를 처리합니다.

기여자 흐름 (모든 PR)

배포되는 코드를 변경하는 모든 PR에는 changeset이 포함되어야 합니다. CI 검사가 이를 강제합니다.

# While working on your PR:
npx changeset

CLI가 범프 유형(major/minor/patch)과 짧은 요약을 묻습니다. .changeset/ 아래에 마크다운 파일을 작성합니다 — 해당 파일을 PR과 함께 커밋하세요.

릴리스가 아닌 PR을 위한 예외 수단(문서, CI, 내부 리팩터링, 동작 영향이 없는 테스트 변경):

• PR에 no-changeset 라벨을 추가하거나, 또는

• npx changeset --empty로 "릴리스 불필요"를 명시적으로 선언합니다.

관리자 흐름 (릴리스 생성)

수동으로 릴리스를 만들지 않습니다. 파이프라인이 처리합니다:

1. changeset 파일이 첨부된 PR이 main에 병합됩니다.

2. **.github/workflows/release.yml**은 main에 대한 모든 푸시에서 실행됩니다. 대기 중인 changeset이 있으면 액션이 작성한 chore(release): version packages PR을 열거나(업데이트)합니다. 해당 PR은:

   • changeset version을 실행하여 대기 중인 changeset을 소비합니다

   • package.json 버전을 올립니다

   • scripts/sync-server-version.mjs를 통해 server.json을 다시 동기화합니다

   • CHANGELOG.md에 항목을 추가합니다

   • 결과를 자체 브랜치에 커밋합니다

3. Version Packages PR을 검토하고 병합하세요 배포할 준비가 되면. 병합 전에 여러 changeset이 누적되도록 둘 수 있습니다 — main에 더 많은 변경이 병합되면 PR이 스스로 업데이트됩니다.

4. 병합하면 릴리스 워크플로가 다시 실행됩니다. 이번에는 대기 중인 changeset이 없으므로 changesets/action이 버전 상승을 감지하고 다음을 수행합니다:

   • npm publish (OIDC trusted publishing, 출처 증명 포함)

   • GitHub 릴리스 + git 태그를 자동으로 생성합니다

5. 워크플로의 마지막 단계는 mcp-publisher를 설치하고 DNS 개인 키로 인증한 다음 com.ffmpeg-micro/mcp-server로 MCP Registry에 게시합니다.

버전 동기화 가드

.github/workflows/release.yml는 main에 대한 모든 푸시에서 버전 일치 검사를 계속 실행합니다. package.json.version, server.json.version, server.json.packages[0].version이 어느 순간이라도 어긋나면 빌드가 명백한 오류와 함께 실패합니다. 보통 scripts/sync-server-version.mjs가 이를 일치하게 유지하지만, 가드는 동기화를 놓친 수동 편집을 잡아냅니다.

검증

Version Packages PR이 병합되고 워크플로가 통과(초록색)된 후:

npm view @ffmpeg-micro/mcp-server version
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.ffmpeg-micro/mcp-server" | jq '.servers[] | {v: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'

예시: 기여자 작업 흐름

새 delete_transcode 도구를 추가한다고 가정해 보겠습니다. PR 흐름:

git switch -c feat/delete-transcode
# ... make the code + test changes ...

npx changeset
# ? Which packages would you like to include? › @ffmpeg-micro/mcp-server
# ? Which type of change is this for @ffmpeg-micro/mcp-server? › minor
# ? Please enter a summary for this change › Add delete_transcode tool

git add .changeset/*.md src/ tests/
git commit -m "feat: add delete_transcode tool"
git push -u origin feat/delete-transcode
gh pr create

CI는 세 가지 검사를 실행합니다:

• test — 단위 테스트

• check (Require changeset) — .changeset/*.md 파일이 있는지 확인

• Vercel — 프리뷰 배포

머지 후, Version Packages PR이 여러분의 항목을 포함해 자동으로 열리거나 업데이트됩니다. 배포할 준비가 되면 해당 PR을 머지하세요.

규칙

• server.json 또는 package.json의 버전 필드를 수동으로 편집하지 마세요. Changesets가 둘 다 관리합니다 — scripts/sync-server-version.mjs가 package.json을 server.json으로 미러링합니다. 둘이 달라지면 CI 드리프트 가드가 릴리스를 실패시킵니다.

• 릴리스를 수동으로 git tag 하지 마세요. changesets/action이 퍼블리시의 일부로 태그와 GitHub Release를 생성합니다. 수동 태그는 새 워크플로에서 인식되지 않습니다.

• Require-changeset 체크를 우회하지 마세요 .changeset/config.json 또는 .changeset/README.md에 변경 사항을 커밋하는 방식은 인정되지 않습니다. npx changeset, no-changeset 라벨, 또는 npx changeset --empty를 사용하세요.

릴리스 관련 파일

• package.json — 버전의 기준이 되는 파일입니다. MCP Registry가 npm 패키지 검증을 위해 필요로 하는 mcpName도 보관합니다. changeset version에 의해 버전이 올라갑니다.

• server.json — MCP Registry 메타데이터입니다. 버전 필드는 package.json에서 자동으로 동기화됩니다.

• .changeset/config.json — Changesets 구성입니다 (공개 액세스, GitHub 인식 체인지로그 포맷터).

• .changeset/*.md — 다음 changeset version 실행에서 사용되기를 기다리는 대기 중인 릴리스 노트입니다.

• scripts/sync-server-version.mjs — package.json 버전을 server.json으로 미러링합니다.

• .github/workflows/release.yml — 퍼블리시 파이프라인입니다 (changesets/action + MCP Registry 스텝).

• .github/workflows/require-changeset.yml — PR에 changeset 존재를 강제합니다.

문제 해결

• Require changeset 체크가 내 PR에서 실패합니다 — npx changeset을 실행하고 생성된 파일을 커밋하세요. 문서 전용 / CI 전용 PR의 경우 no-changeset 라벨을 추가하거나 npx changeset --empty를 사용하세요.

• 버전 동기화 가드 단계에서 CI가 실패합니다 — server.json이 수동으로 편집된 것입니다. 로컬에서 node scripts/sync-server-version.mjs를 실행하고 커밋 후 푸시하세요. 가드는 package.json.version, server.json.version, server.json.packages[0].version을 비교합니다.

• changesets/action이 내 기능 PR이 머지된 후 Version Packages PR을 열지 않았습니다 — PR의 .changeset/*.md 파일에 실제로 내용이 있었는지 확인하세요 (bump 타입과 요약이 포함된 비어 있지 않은 front matter). 빈 changeset은 '릴리스 불필요'를 의미하며 의도적으로 무시됩니다.

• mcp-publisher publish가 "package not found" 오류로 실패합니다 — npm이 새 버전을 아직 전파하지 못한 것입니다. 릴리스 워크플로의 Determine if MCP Registry publish is needed 스텝은 npm view를 최대 ~50초 동안 재시도하며, 버전이 아직 라이브 상태가 아니면 대기한 뒤 레지스트리 퍼블리시를 다음 main 푸시로 미룹니다 (그렇게 하면 드리프트가 자동으로 해결됩니다). 수동 실행에서 이 오류가 보이면 30초 기다렸다가 다시 퍼블리시하세요.

• MCP Registry가 npm보다 한 버전 뒤처져 있습니다 — Determine if MCP Registry publish is needed 스텝이 건너뛰었거나 needed=false를 반환했습니다. main에 아무 커밋이나 푸시해 재실행을 트리거하세요. 게이트는 package.json ↔ npm ↔ registry를 비교하고 자동으로 따라잡습니다. 계속 건너뛰면 스텝의 로그 출력에서 각 소스가 보고한 버전을 확인하세요.

• mcp-publisher publish가 "mcpName mismatch" 검증 오류로 실패합니다 — package.json의 mcpName은 server.json의 name과 같아야 합니다 (둘 다 com.ffmpeg-micro/mcp-server여야 합니다).

• mcp-publisher login dns가 "public key mismatch" 오류로 실패합니다 — MCP_PRIVATE_KEY 시크릿이 ffmpeg-micro.com의 TXT 레코드와 더 이상 일치하지 않습니다. 로컬에서 키페어를 다시 생성하고 TXT 레코드와 GitHub 시크릿을 모두 업데이트하세요.

라이선스

MIT — LICENSE를 참조하세요.