# MCP 서버 연결 > Claude, ChatGPT, VS Code 등에 transcript1을 연결해 영상과 파일을 텍스트로 변환하세요. Cursor와 Claude Code의 MCP 설정 방법도 안내해요. Canonical: https://transcript1.com/ko/docs/mcp Language: ko Last updated: 2026-10-15 transcript1의 원격 [Model Context Protocol](https://modelcontextprotocol.io/) 서버를 AI 어시스턴트에 연결하세요. YouTube, X, TikTok, Instagram, Facebook, Bluesky의 영상 링크나 업로드한 오디오·영상 파일을 텍스트로 변환하고, 완성된 스크립트를 어시스턴트가 읽을 수 있어요. 그 밖에 지원하는 공개 녹화 영상과 제한 사항은 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)에서 확인하세요. 공개 게시물만 사용할 수 있으며 영상이 여러 개면 첫 번째 영상만 변환해요. YouTube와 X의 자막 지원은 그대로예요. TikTok, Bluesky, Dailymotion, LinkedIn에서도 영상 원본 언어의 자막을 사용할 수 있어요. auto에서는 사용할 자막이 없으면 AI 음성 텍스트 변환(STT)으로 전환해요. 분당 요금은 같아요. YouTube 외 플랫폼의 자막은 자동 생성 자막도 세그먼트별 타임스탬프만 있어요(`words: null`). `captions`(자막만)는 오디오 다운로드나 STT를 실행하지 않아요. 화자 분리를 켜거나 `source=stt`를 지정하면 자막 대신 음성을 변환해요. 자세한 기준은 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)을 확인하세요. - **서버 주소:** `https://api.transcript1.com/mcp` (Streamable HTTP) - **연결 인증:** Claude와 ChatGPT에서는 OAuth 2.1로 transcript1에 로그인하고 접근을 승인해요. Cursor, VS Code, Claude Code, 에이전트에서는 API 키를 `Authorization: Bearer t1_...` 헤더로 보내세요. 키는 [“API keys” 페이지](https://transcript1.com/dashboard/account/tokens)에서 발급받을 수 있어요. MCP 도구는 연결한 계정의 인증 정보로 `/v1` [REST API](https://transcript1.com/ko/docs/api-reference)를 호출해요. 입력값 검증, 크레딧 차감, 오류 코드도 REST API와 같아요. MCP 전용 한도나 분량이 따로 있는 것은 아니며, 다른 요청과 계정의 요청 한도·분량을 함께 사용해요. ## 사용할 수 있는 도구 | 도구 | 기능과 입력값 | |---|---| | `transcribe` | `url`의 영상을 텍스트로 변환해요. `platform`, `source`, `language`, `diarize`, `format`, `wait_seconds`는 생략할 수 있어요. 플랫폼은 링크로 알아내요. 완료되면 스크립트 첫 페이지를, 아직 처리 중이면 `id`를 반환해요. | | `get_transcription` | `id`로 작업 상태나 스크립트를 조회해요. 필요하면 `wait_seconds`, `format`, `from_seconds`, `max_chars`를 지정하세요. | | `list_transcriptions` | 최근 작업을 최신순으로 조회해요. 스크립트 본문은 포함하지 않아요. `status`, `platform`, `limit`, `cursor`로 조회 조건을 지정할 수 있어요. | | `create_upload` | 파일을 청크로 올릴 수 있도록 예약해요. `filename`, `size`, 직접 생성한 UUID인 `request_id`가 필요해요. `mime_type`, `language`, `diarize`는 선택 사항이에요. | | `get_upload_status` | 서버에 도착한 청크를 조회해 중단된 업로드를 이어갈 수 있어요. | | `complete_upload` | 업로드한 청크를 검사한 뒤 변환 작업을 대기열에 넣어요. | | `delete_transcription` | 진행 중이면 취소하고 차감한 분량을 돌려드려요. 이미 끝난 작업은 스크립트와 함께 삭제해요. | | `get_account` | 남은 분량, 현재 요금제, 갱신일을 확인해요. | ### 응답 형식과 기본 설정 - 기본 `format`은 `text`예요. 세그먼트마다 한 줄로 출력하며 타임스탬프를 붙여요. 화자 분리를 했다면 `[00:01:02] Speaker 1: Good morning.`처럼 화자도 표시해요. `srt`, `vtt`, `json` 형식도 선택할 수 있어요. - `wait_seconds`는 기본 50초이며 0~55초로 지정할 수 있어요. 기다린 뒤에도 처리 중이면 응답에 상태와 `id`가 나와요. 이 ID로 `get_transcription`을 호출해 다시 기다리세요. - 긴 스크립트는 여러 페이지로 나눠요. `max_chars`는 기본 60,000이며 1,000~100,000 사이에서 지정할 수 있어요. 세그먼트 중간에서 끊지 않고 응답에 `next_from_seconds`를 넣어요. 다음 페이지를 받으려면 이 값을 `from_seconds`로 보내세요. - 모든 응답에서 `transcript_source`로 출처를 확인할 수 있어요. 값은 `youtube_captions`, `x_captions`, `tiktok_captions`, `bluesky_captions`, `dailymotion_captions`, `linkedin_captions`, `speech_to_text`예요. `caption_kind: null`은 자막의 출처를 모른다는 뜻이에요. 업로더가 올린 자막으로 해석하면 안 돼요. ### 다시 보내기 전에 기존 작업 확인하기 `transcribe`는 항상 `reuse_recent`를 사용해요. 전체 영상 링크와 같은 옵션으로 24시간 안에 다시 요청하면 이전 작업을 반환하고 추가 차감하지 않아요. 단축 링크는 이 방식으로 재사용할 수 없어요. 기존 작업을 재사용했는지는 응답에 표시해요. 이미 접수한 작업의 진행 상황은 새로 제출하지 말고 `get_transcription`이나 `list_transcriptions`로 확인하세요. ### 파일 업로드 흐름 파일 데이터 자체는 MCP로 보낼 수 없어요. `create_upload`를 호출하면 작업 `id`, 청크 URL 템플릿, `X-Upload-Token`, 청크 목록을 받아요. 어시스턴트는 MCP 외부에서 HTTP `PUT`으로 청크를 보내고, 전송을 마치면 `complete_upload`를 호출해요. 응답에는 직접 파일을 올릴 수 있는 대시보드 업로드 페이지도 안내해요. 전송 규약은 [파일 업로드](https://transcript1.com/ko/docs/uploads)를 확인하세요. ### 웹훅은 REST API로 사용 MCP 도구는 웹훅 파라미터를 받지 않아요. 완료 알림이 필요하면 REST API의 [웹훅](https://transcript1.com/ko/docs/webhooks)을 사용하세요. ## Claude Claude에서는 커스텀 커넥터로 원격 MCP 서버를 등록하세요. 1. Claude의 커넥터 설정에서 커스텀 커넥터 추가를 선택하세요. 2. 이름에 `transcript1`, 서버 URL에 `https://api.transcript1.com/mcp`를 넣으세요. 3. 로그인 화면이 나오면 transcript1 계정으로 로그인하고 접근을 허용하세요. 요청하는 권한은 `transcriptions:read`, `transcriptions:write`예요. 연결 후 “https://www.youtube.com/watch?v=dQw4w9WgXcQ 영상을 텍스트로 변환해 줘”라고 요청해 보세요. 커스텀 커넥터 지원 여부는 Claude 요금제에 따라 달라요. ## ChatGPT ChatGPT에서도 MCP 서버를 커스텀 커넥터로 등록할 수 있어요. 1. ChatGPT 커넥터 설정에서 MCP 서버용 커스텀 커넥터를 추가하세요. 2. 서버 주소에 `https://api.transcript1.com/mcp`를 넣으세요. 3. transcript1 계정으로 로그인한 뒤 접근을 허용하세요. 사용 가능 여부는 ChatGPT 요금제와 워크스페이스 설정에 따라 달라요. 개발자 모드를 켜야 할 수도 있어요. ## Cursor에 MCP 연결하기 [Cursor에 transcript1 추가](cursor://anysphere.cursor-deeplink/mcp/install?name=transcript1&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmFuc2NyaXB0MS5jb20vbWNwIn0=) 링크로 서버를 바로 설치할 수 있어요. 직접 설정하려면 `.cursor/mcp.json`에 아래 내용을 넣으세요. `Authorization` 헤더에는 API 키를 지정하세요. ```json { "mcpServers": { "transcript1": { "url": "https://api.transcript1.com/mcp", "headers": { "Authorization": "Bearer t1_YOURKEY" } } } } ``` ## VS Code [VS Code에 transcript1 추가](vscode:mcp/install?%7B%22name%22%3A%22transcript1%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.transcript1.com%2Fmcp%22%7D) 링크로 서버를 바로 설치할 수 있어요. 수동으로 설정하려면 워크스페이스의 `.vscode/mcp.json`에 아래 내용을 넣으세요. ```json { "servers": { "transcript1": { "type": "http", "url": "https://api.transcript1.com/mcp", "headers": { "Authorization": "Bearer t1_YOURKEY" } } } } ``` ## Claude Code에 MCP 연결하기 아래 명령의 `t1_YOURKEY`에 발급받은 API 키를 넣고 실행하세요. ```bash claude mcp add --transport http transcript1 https://api.transcript1.com/mcp --header "Authorization: Bearer t1_YOURKEY" ``` ## 다른 MCP 클라이언트에서 연결하기 원격 MCP 서버를 지원한다면 다른 클라이언트에서도 연결할 수 있어요. 서버 URL은 `https://api.transcript1.com/mcp`, 인증 헤더는 `Authorization: Bearer t1_...`로 설정하세요. ## 명령어로 연결하기: Claude Desktop 등 MCP 서버를 명령어로 실행하는 클라이언트라면 `TRANSCRIPT1_API_KEY`를 설정하고 `npx -y @transcript1/mcp`를 실행하세요. 이 패키지가 원격 transcript1 서버에 연결해요. Node.js 18 이상이 필요해요. Claude Desktop은 `claude_desktop_config.json`에 아래 설정을 추가하세요. `t1_YOURKEY`에는 [“API keys” 페이지](https://transcript1.com/dashboard/account/tokens)에서 발급받은 키를 넣으세요. ```json { "mcpServers": { "transcript1": { "command": "npx", "args": ["-y", "@transcript1/mcp"], "env": { "TRANSCRIPT1_API_KEY": "t1_YOURKEY" } } } } ``` ## Agent Skill Agent Skill은 transcript1 사용 방법을 적은 짧은 `SKILL.md` 파일이에요. 스킬을 지원하는 에이전트에 [https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md](https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md)의 파일을 추가하세요. 스킬을 자동으로 탐색하는 에이전트는 `https://transcript1.com/.well-known/agent-skills/index.json`에서 이 파일을 찾을 수 있어요. ## 도구 호출이 실패한 경우 도구 호출이 실패하면 REST API와 같은 `code`에 오류 설명과 해결 방법을 덧붙여요. 어시스턴트는 이 안내를 보고 다음 행동을 정할 수 있어요. 형식은 `: . `이며, 사용 가능한 분량을 다 쓰면 다음처럼 나와요. ```text insufficient_minutes: 20 minutes needed, 3 remaining. Top up at https://transcript1.com/dashboard/billing ``` 코드별 의미는 [오류 처리](https://transcript1.com/ko/docs/errors)에서 확인하세요. 변환 도중 실패한 작업도 `media_private`, `no_captions` 같은 원인 코드로 같은 형식의 오류를 반환해요.