media-mcp

소셜 미디어를 손끝으로. Twitter/X, YouTube, Instagram, 그리고 영상 처리에 걸친 31가지 도구 — Claude Desktop, Claude Code, 또는 모든 MCP 클라이언트에서 사용 가능합니다. 100% 오픈소스입니다.

트윗을 가리키면 전체 텍스트, 지표, 영상 전사(transcription)를 얻을 수 있습니다. YouTube URL을 주면 대본(transcript)을 받습니다. Instagram 릴을 넣으면 미디어를 다운로드하고 오디오를 전사합니다. 모든 전사는 Whisper를 통해 로컬에서 실행됩니다 — 오디오가 기기를 떠나지 않습니다.

핵심 논지: 귀는 항상, 눈은 귀가 실패할 때만

작은 Whisper 모델은 듣는 데는 뛰어나지만 읽는 데는 형편없습니다. 흔하지 않은 이름을 잘못 알아듣습니다. 화면의 텍스트는 전사하지 못합니다. 자막으로 박힌 캡션은 건너뜁니다. 영상에 대한 질문의 90%에서는 이 정도로 충분합니다 — 대략적인 내용이면 되니까요.

하지만 사용자가 "이 릴에서 설치 명령어가 뭐예요?" 또는 *"그가 보여준 핸들이 뭐예요?"*라고 물으면, 전사만으로는 자신 있게 틀린 답을 내놓습니다. URL은 화면에 있었습니다. 고유명사는 캡션에 철자까지 적혀 있었습니다. Whisper는 그중 어떤 것도 보지 못했습니다.

media-mcp는 whisper-cli -ojf로 토큰별 신뢰도(per-token confidence)를 포함해 전사하고, 불확실 구간(Whisper가 추측 중임을 인정한 곳)과 지시적 표현("visit our", "this command", "in the bio" — 화면의 콘텐츠가 언급되고 있다는 강력한 신호)에 플래그를 표시합니다. LLM은 그 마커를 읽고, 시각적 검증이 필요한 특정 타임스탬프에 get_video_frames_at을 호출할지 결정합니다. 프레임은 필요할 때만 나옵니다. LLM의 자체 비전이 읽기를 수행합니다 — OCR도, 두 번째 모델도 없습니다.

결과: 에이전트는 모든 영상에 귀를 갖고, 귀가 실패하는 곳에서만 눈을 사용합니다. 최소 프레임, 최대 정확도.

Related MCP server: youtube-mcp

기능

• 가져오기: Twitter/X에서 트윗, 스레드, 프로필, 팔로워, 트렌드, 검색 결과를 가져옵니다 (TwitterAPI.io REST API 기반 26개 도구, 중복 읽기 도구에는 선택적으로 Xquik 지원)

• 전사: whisper-cli로 영상 오디오를 로컬에서 전사 — 미디어 다운로드, ffmpeg로 오디오 추출, 사용자 하드웨어에서 Whisper 실행, 토큰별 신뢰도와 지시적 표현 감지를 출력하여 LLM이 오디오 채널이 신뢰할 수 없는 위치를 알 수 있게 합니다

• 다운로드: 자체 호스팅 Cobalt 인스턴스를 통해 Instagram 게시물, 릴, 캐러셀을 로컬 폴더로 다운로드

• 프레임 추출: 모든 영상 URL에서 설정 가능한 FPS로 프레임 추출 — 또는 get_video_frames_at으로 타임스탬프 배열에 정밀하게 추출 (캐시 인식, 후속 요청 시 재다운로드 없음)

• 모니터링: Twitter 사용자를 실시간으로 모니터링하고 키워드 규칙으로 트윗 필터링

• 캐싱: 다운로드한 영상을 ~/.media-mcp/cache/videos/에 캐시 (URL의 sha256 키, 24시간 TTL) — 같은 영상의 전사 + 프레임 조회가 한 번의 다운로드로 처리됩니다

작동 방식

LLM은 HTML을 스크래핑하거나 DOM을 파싱하지 않습니다. 모든 도구는 목적에 맞게 만들어진 API를 호출하고 구조화된 LLM 친화적 텍스트를 반환합니다.

텍스트 데이터(트윗, 프로필, 트렌드): 기본적으로 TwitterAPI.io에 REST 호출 한 번으로, 포맷된 출력으로 파싱됩니다. TWITTER_BACKEND=xquik과 XQUIK_API_KEY를 설정하면 중복 읽기 도구에 Xquik을 사용합니다.

전사(트윗 영상, YouTube, Instagram 릴): 파이프라인은 미디어를 공유 캐시에 다운로드하고, ffmpeg로 오디오를 추출(16kHz 모노 WAV)한 뒤, 토큰별 확률을 보존하기 위해 -ojf(output-json-full) 플래그로 whisper-cli를 실행하고, 인라인 ⟨token p=0.XX⟩ 마커와 불확실 구간 및 지시적 표현 요약 블록이 포함된 LLM이 읽을 수 있는 전사본을 반환합니다. YouTube의 경우 자막을 먼저 시도합니다(즉시 처리) — Whisper는 폴백입니다.

시각 데이터(Instagram 이미지, 영상 프레임): 미디어를 로컬 폴더에 다운로드하고 절대 파일 경로를 반환하여 LLM이 비전으로 직접 읽을 수 있게 합니다. 프레임 추출에는 두 가지 모드가 있습니다: 대량(extract_video_frames, 설정 가능한 FPS)과 정밀(get_video_frames_at — 타임스탬프당 JPG 하나, 전사 불확실 지점의 정밀 검증용).

파이프라인

URL ──► Detect platform
             │
             ├── Twitter ──► TwitterAPI.io or Xquik REST ──► structured text
             │                     │
             │               has video? ──► cache ──► ffmpeg ──► whisper-cli -ojf
             │                                                         │
             │                                       transcript + confidence markers
             │
             ├── YouTube ──► try captions (instant)
             │                     │
             │               no captions? ──► yt-dlp ──► ffmpeg ──► whisper-cli -ojf
             │
             ├── Instagram ──► Cobalt API ──► download to cache
             │                     │
             │               has video? ──► ffmpeg ──► whisper-cli -ojf
             │
             ├── Video URL ──► cache ──► ffmpeg -vf fps=N ──► frame JPGs
             │
             └── Video URL + timestamps[] ──► cache ──► ffmpeg -ss each ──► one JPG per timestamp
                 (for targeted verification when transcription uncertainty demands it)

전사에는 항상 토큰별 신뢰도와 지시적 표현 스캔이 포함됩니다. LLM은 그 신호가 필요하다고 말할 때 프레임 추출로 라우팅합니다.

모든 전사는 로컬에서 이루어집니다. 모든 임시 파일은 정리됩니다. 다운로드한 영상은 24시간 동안 공유 캐시(~/.media-mcp/cache/videos/)에 보관되어 같은 URL에 대한 후속 호출이 재다운로드하지 않습니다. LLM은 구조화된 텍스트 또는 파일 경로를 받습니다 — 원시 API JSON은 절대 아닙니다.

설계 원칙

1. 구조화된 데이터, 스크래핑 금지. 모든 도구는 목적에 맞게 만들어진 API를 호출합니다. HTML 파싱 없음, 취약한 셀렉터 없음, 브라우저 자동화 없음.

2. 로컬 전사만. 오디오는 기기를 떠나지 않습니다. Whisper는 로컬 하드웨어에서 실행됩니다.

3. 자막 우선, Whisper 차선. 플랫폼이 이미 처리한 작업에 컴퓨팅을 낭비하지 마세요.

4. 도구 하나, 작업 하나. 모드 플래그가 있는 다목적 도구는 없습니다. 각 도구는 정확히 한 가지 일만 합니다.

5. 시각 콘텐츠는 파일 경로로. 절대 경로를 반환하여 LLM이 이미지를 직접 볼 수 있게 합니다.

6. 귀는 항상, 눈은 귀가 실패할 때만. 전사는 저렴하고 비전 토큰은 비쌉니다. LLM은 Whisper가 확신하지 못한다고 인정한 타임스탬프, 또는 화자가 화면의 무언가를 명시적으로 언급하는 타임스탬프에서만 프레임을 봅니다. 1fps가 아닙니다. 키프레임도 아닙니다. 정확도가 실제로 필요한 바로 그 위치에서만.

7. OCR 레이어 없음. Claude의 비전이 프레임을 직접 읽습니다. 하나의 모델이 모든 멀티모달 추론을 수행하는 것이 OCR과 비전이 경쟁하는 두 모델의 이음새보다 낫습니다.

전체 파이프라인 세부 사항, 도구 참조, 안티패턴은 SKILL.md를 참조하세요.

시작하기

npx (가장 빠름)

TWITTER_API_KEY=your_key npx media-mcp

또는 한 줄로 Claude Code에 등록:

claude mcp add media-mcp -e TWITTER_API_KEY=your_key -- npx media-mcp

Whisper base 모델은 첫 전사 시 ~/.media-mcp/models/에 자동으로 다운로드됩니다. ffmpeg, whisper-cli, yt-dlp는 여전히 설치해야 합니다(사전 요구사항 참조).

Docker

docker run -i --rm \
  -e TWITTER_API_KEY=your_key \
  -v media-mcp-data:/data \
  ghcr.io/woosal1337/media-mcp

이미지에는 ffmpeg, yt-dlp, whisper-cli가 번들되어 있습니다. 모델과 영상 캐시는 /data 볼륨에 유지됩니다.

소스에서

git clone https://github.com/woosal1337/media-mcp.git
cd media-mcp
npm install && npm run build

Whisper 모델 다운로드(선택 사항 — 건너뛴 모델은 요청 시 가져옵니다):

mkdir -p models
curl -L -o models/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

.env 생성:

cp .env.example .env
# Edit with your keys:
# TWITTER_API_KEY=your_twitterapi_io_key
# Optional Xquik backend for overlapping read tools:
# TWITTER_BACKEND=xquik
# XQUIK_API_KEY=your_xquik_key
# XQUIK_BASE_URL=https://xquik.com/api/v1
# WHISPER_MODEL_PATH=/absolute/path/to/models/ggml-base.bin
# COBALT_API_URL=http://localhost:9000       (optional, for Instagram)
# COBALT_API_KEY=your_cobalt_key             (optional)
# CLOUDFLARE_ACCOUNT_ID=your_account_id     (optional, for fetch_markdown)
# CLOUDFLARE_API_TOKEN=your_api_token       (optional, for fetch_markdown)

사전 요구사항

구성

Claude Code

~/.claude/settings.json에 추가:

{
  "mcpServers": {
    "media-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/media-mcp/dist/index.js"],
      "env": {
        "TWITTER_API_KEY": "your_key",
        "TWITTER_BACKEND": "twitterapi",
        "WHISPER_MODEL_PATH": "/absolute/path/to/media-mcp/models/ggml-base.bin",
        "COBALT_API_URL": "http://localhost:9000",
        "COBALT_API_KEY": "your_cobalt_key",
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id",
        "CLOUDFLARE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가 — 위와 동일한 구조입니다.

환경 변수

도구

Twitter/X — 26개 도구

TwitterAPI.io는 모든 Twitter/X 도구의 기본 백엔드입니다. TWITTER_BACKEND=xquik과 XQUIK_API_KEY를 설정하면 중복 읽기 도구를 Xquik으로 보냅니다. 두 백엔드 모두 동일한 도구 출력을 반환하므로 다른 것은 변경되지 않습니다.

TwitterAPI.io 전용 도구는 TWITTER_API_KEY 없이 TWITTER_BACKEND=xquik로 실행하면 명확한 오류를 발생시킵니다. 두 키를 모두 설정하면 모든 도구를 사용하면서도 Xquik을 통해 읽을 수 있습니다.

트윗 가져오기

프로필 가져오기

실시간 모니터링

YouTube — 도구 1개

Instagram — 도구 1개

Cloudflare — 도구 1개

비디오 — 도구 2개

전사 작동 방식

video → cache → ffmpeg -ar 16000 -ac 1 → audio.wav → whisper-cli -ojf → audio.wav.json
                                                                            │
                                                                            ▼
                                                         parse per-token probabilities
                                                                            │
                                                                            ▼
                                        transcript with ⟨token p=0.XX⟩ markers
                                        + Uncertainty zones summary (midpoint_s each)
                                        + Demonstrative phrases block (midpoint_s each)

1. 비디오가 ~/.media-mcp/cache/videos/<sha256>.mp4에 다운로드됩니다(있으면 재사용, 24시간 미만)

2. ffmpeg가 오디오를 16kHz 모노 WAV로 추출합니다

3. whisper-cli가 -ojf(output-json-full)로 로컬 전사 — JSON에 토큰별 p 값 포함

4. p=0.5 미만의 토큰은 연속 범위(≤150ms 간격)로 병합되어 불확실 구간으로 보고됩니다

5. 세그먼트 텍스트에서 화면 콘텐츠를 참조하는 전형적인 지시적 표현을 스캔합니다

6. LLM은 세그먼트 수준 전사본 + 불확실 구간 + 지시적 표현 적중을 받고, 관련 타임스탬프로 get_video_frames_at을 호출할지 결정합니다

YouTube의 경우 자막이 먼저 시도됩니다(즉시 제공, 이미 타임스탬프 포함). Whisper는 대체 수단입니다. 모든 전사는 로컬에서 이루어집니다 — 오디오가 외부 서비스로 전송되지 않습니다.

Cobalt 설정

Cobalt은 21개 플랫폼을 지원하는 오픈소스 미디어 다운로더입니다. media-mcp는 Instagram에 이를 사용합니다. 자체 인스턴스가 필요합니다 — 공개 API는 서버 간에 작동하지 않는 JWT 인증을 요구합니다.

Docker(권장)

# docker-compose.yml
services:
  cobalt:
    image: ghcr.io/imputnet/cobalt:11
    init: true
    read_only: true
    restart: unless-stopped
    ports:
      - 9000:9000/tcp
    environment:
      API_URL: "http://localhost:9000/"
    labels:
      - com.centurylinklabs.watchtower.scope=cobalt

  watchtower:
    image: ghcr.io/containrrr/watchtower
    restart: unless-stopped
    command: --cleanup --scope cobalt --interval 900 --include-restarting
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

docker compose up -d
curl http://localhost:9000/   # verify

API 키 인증 추가

node -e "console.log(crypto.randomUUID())"   # generate key

keys.json 생성:

{
  "your-uuid": {
    "name": "media-mcp",
    "limit": "unlimited",
    "allowedServices": "all"
  }
}

cobalt 환경에 추가:

environment:
  API_KEY_URL: "file:///keys.json"
  API_AUTH_REQUIRED: 1
volumes:
  - ./keys.json:/keys.json:ro

쿠키 추가(비공개 콘텐츠용)

Instagram sessionid로 cookies.json을 생성하고 /cookies.json으로 마운트한 다음 환경에 COOKIE_PATH: "/cookies.json"을 설정합니다.

프로덕션 강화

environment:
  CORS_WILDCARD: 0
  CORS_URL: "http://localhost"
  RATELIMIT_WINDOW: 60
  RATELIMIT_MAX: 100
  DURATION_LIMIT: 10800

지원 플랫폼

Cobalt는 21개 플랫폼을 지원합니다. 현재 media-mcp는 Instagram에 이를 사용합니다. 향후 버전에서 더 추가될 예정입니다: YouTube, TikTok, Twitter/X, Reddit, Facebook, Pinterest, Snapchat, Bluesky, Twitch, Vimeo, SoundCloud, Dailymotion, Tumblr, Bilibili, Loom, Streamable, Rutube, Newgrounds, OK.ru, VK.

원클릭 설정

PROMPT.md의 내용을 복사하여 Claude Code에 붙여넣습니다. 모든 사전 요구사항을 설치하고, 저장소를 클론하고, 모든 것을 구성하고, media-mcp를 자동으로 연결합니다.

전사 언어 및 모델

세 가지 전사 도구 모두 두 가지 선택적 매개변수를 허용합니다:

• language — ISO 639-1 코드(en, es, tr, de, ...) 또는 자동 감지용 auto. 기본값은 영어입니다. YouTube에서는 Whisper 실행 전에 이 언어로 자막을 요청합니다.

• model — tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3 또는 large-v3-turbo. 알려진 이름은 HuggingFace에서 ~/.media-mcp/models/로 한 번 다운로드되어 재사용됩니다. 모든 ggml .bin 파일의 절대 경로도 작동합니다. 더 큰 모델은 더 느리지만 더 정확합니다 — large-v3-turbo는 base가 너무 많이 잘못 들을 때 최적의 선택입니다.

개발

npm run dev        # watch mode (recompiles on change)
npm run build      # one-time build
npm test           # run the unit test suite
npm run test:watch # tests in watch mode
npm start          # run the server

CI는 모든 푸시와 PR에 대해 Node 20 및 22에서 빌드와 테스트를 실행합니다. 릴리스는 태그로 트리거됩니다. v*를 푸시하면 출처(provenance)와 함께 npm에 게시되고, GitHub Release가 생성되며 Docker 이미지가 GHCR로 푸시됩니다.

라이선스

MIT