Skip to main content
Glama

media-mcp (Node.js)

中文 | English

npm version Node.js >=18 License: MIT

MCP 프로토콜 기반의 비디오 향상 및 이미지 세분화 서비스로, MCP Client-Server와 백엔드 HTTP Server 간의 상호작용을 수행합니다.

기능

다음과 같은 MCP 도구를 제공합니다:

  • create_task - 비디오 향상 작업 생성 (URL 또는 로컬 파일 업로드 지원)

  • get_task_status - 작업 상태 조회

  • enhance_video_sync - 동기식 비디오 향상 (완료될 때까지 차단)

  • sam3_predict - SAM3 이미지 세분화 (로컬 경로, URL 또는 Base64 이미지 지원)

Related MCP server: Grok Imagine Video MCP Server

사전 요구 사항

  • Node.js >= 18 (확인: node --version)

  • API Key (인증용, 서비스 제공업체에 문의하여 획득)

간편 설치 (권장)

사용 중인 AI 에이전트에 확정된 MCP 구성 경로가 있는 경우, 아래 문장을 복사하여 AI에게 보내십시오:

帮我安装 npm 包 @avclabs.ai/media-mcp 作为 MCP server。我的 API Key 是:sk-xxxxxxxx。

AI가 자동으로 다음 작업을 완료합니다:

  1. 사용 중인 MCP 클라이언트 감지

  2. 구성 파일 경로 찾기

  3. 올바른 구성 작성

  4. 클라이언트 재시작 안내

수동 설치

설치가 필요 없으며, MCP 클라이언트 구성에서 npx를 사용하여 직접 실행하십시오.

1. Claude Code (CLI)

Claude Code에서 실행:

/mcp

출력에서 **"User MCPs"**에 해당하는 구성 파일 경로를 확인한 후 해당 파일을 편집하십시오.

일반적인 경로 (/mcp를 사용할 수 없는 경우):

  • Windows: %USERPROFILE%\.claude.json

  • macOS: ~/.claude.json

  • Linux: ~/.claude.json

  • 구버전/대체: ~/.claude/mcp.json

다음 내용을 붙여넣으십시오 (your-api-key를 실제 API Key로 교체):

{
  "mcpServers": {
    "video-enhancement": {
      "command": "npx",
      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

저장 후 /mcp를 실행하여 로드 성공 여부를 확인하십시오.

2. Cursor

설정 > Tools & MCPs > Add New MCP Server로 이동:

  • Name: video-enhancement

  • Type: command

  • Command:

env HTTP_API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest

또는 ~/.cursor/mcp.json 편집:

{
  "mcpServers": {
    "video-enhancement": {
      "command": "npx",
      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

설치 확인

클라이언트를 재시작한 후 도구가 성공적으로 로드되었는지 확인하십시오:

  1. 또는 AI에게 직접 질문: "사용 가능한 도구가 무엇인가요?"

  2. 다음이 보여야 합니다: create_task, get_task_status, enhance_video_sync, sam3_predict

구성 항목

변수명

필수

기본값

설명

API_KEY

예

-

API 인증 키 (비디오 향상 및 SAM3 공용)

HTTP_API_BASE_URL

아니요

https://mcp.avc.ai/enhance

비디오 향상 서비스 인터페이스 주소

SAM3_API_BASE_URL

아니요

https://mcp.avc.ai/sam

SAM3 서비스 인터페이스 주소

SAM3_POLL_INTERVAL

아니요

2000

폴링 간격 (밀리초)

SAM3_POLL_MAX_ATTEMPTS

아니요

60

최대 폴링 횟수

사용자 지정 서비스 주소

{
  "env": {
    "HTTP_API_BASE_URL": "https://your-endpoint.com",
    "API_KEY": "your-api-key",
    "SAM3_API_BASE_URL": "http://localhost:8001"
  }
}

또는 명령줄 인수를 통해:

npx -y @avclabs.ai/media-mcp@latest --base-url https://your-endpoint.com --api-key your-api-key --sam3-base-url http://localhost:8001

사용 예시

구성이 완료되면 AI에게 자연어로 다음과 같이 말하십시오:

"이 비디오를 1080p로 향상시켜 줘: https://example.com/video.mp4"

"내 바탕화면의 video.mp4를 2k 화질로 높여줘"

AI가 자동으로 해당 도구를 호출하여 작업을 완료합니다.

"이 이미지를 분석해서 안에 있는 모든 물체를 찾아줘: C:\Users\xxx\photo.png"

"SAM3로 이 이미지를 세분화해 줘, 프롬프트는 'find all cars'"

제공되는 도구

create_task

비디오 향상 작업 생성 (비동기).

매개변수

유형

필수

기본값

설명

video_source

string

예

-

비디오 URL 또는 로컬 파일 경로 (URL은 공개적으로 액세스 가능해야 하며, 로그인이나 서명이 필요한 링크는 지원하지 않음)

type

string

아니요

url

url 또는 local

resolution

string

아니요

720p

480p, 540p, 720p, 1080p, 2k

반환값:

{
  "success": true,
  "task_id": "xxx",
  "status": "wait"
}

get_task_status

작업 상태 조회.

매개변수

유형

필수

task_id

string

예

반환값:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "video_url": "https://..."
}

enhance_video_sync

동기식 비디오 향상 (완료될 때까지 차단).

매개변수

유형

필수

기본값

설명

video_source

string

예

-

비디오 URL 또는 로컬 파일 경로 (URL은 공개적으로 액세스 가능해야 함)

type

string

아니요

url

url 또는 local

resolution

string

아니요

720p

목표 해상도

poll_interval

number

아니요

5

폴링 간격 (초)

timeout

number

아니요

600

타임아웃 시간 (초)

sam3_predict

SAM3 세분화 API를 사용하여 이미지를 분석하고 추론 결과(masks, boxes, scores)를 생성합니다.

매개변수:

이미지 입력 (세 가지 중 하나 필수):

  • imagePath (string): 로컬 이미지의 절대 경로. 일반적인 이미지 형식(PNG, JPG, JPEG 등) 지원.

    • 예: "C:\\Users\\xxx\\photo.png", "/home/user/images/cat.jpg"

  • imageUrl (string): 공개적으로 액세스 가능한 이미지 URL.

    • 예: "https://example.com/photo.jpg"

  • imageBase64 (string): Base64 인코딩된 이미지 데이터.

    • 예: "iVBORw0KGgoAAAANSUhEUgAA..."

기타 매개변수:

  • prompt (string, required): 이미지에서 세분화할 대상 물체를 지정하는 영어 텍스트 프롬프트. 예: "person", "car", "a cat sitting on a sofa". SAM3 모델은 영어 프롬프트만 허용하므로 영어 설명을 권장합니다.

반환:

추론 완료 후 JSON 문자열을 직접 반환합니다. 이 JSON에는 다음 세 가지 필드가 포함됩니다:

  • masks: 2차원 배열. 각 요소는 입력 이미지와 크기가 같은 이진 마스크(0 또는 1)입니다.

  • boxes: 2차원 배열. 각 요소는 [x1, y1, x2, y2] 형식의 경계 상자 좌표입니다.

  • scores: 1차원 배열. 각 요소는 해당 감지 결과의 신뢰도 점수(0~1)입니다.

결과 JSON 내용 예시:

{
  "masks": [
    [[0, 0, 1, ...], [0, 1, 1, ...], ...],
    [[0, 0, 0, ...], [0, 0, 1, ...], ...]
  ],
  "boxes": [
    [120, 80, 300, 450],
    [400, 200, 600, 500]
  ],
  "scores": [0.95, 0.87]
}

자주 묻는 질문

첨부 파일을 드래그한 후 파일을 찾을 수 없다고 나오나요?

stdio MCP의 알려진 제한 사항입니다. Agent 인터페이스를 통해 파일을 드래그하거나 업로드할 때 파일 경로가 MCP Server로 전달되지 않을 수 있습니다.

해결 방법:

  1. 경로를 함께 제공 (권장): 이미지를 드래그한 후 텍스트에 로컬 절대 경로를 추가하십시오.

  2. 자동 인코딩 대기: Claude가 자동으로 이미지를 base64로 인코딩할 수 있습니다.

  3. 경로 질문에 답변: Claude가 경로를 물어보면 로컬 절대 경로를 직접 입력하십시오.

세 가지 입력 방식에 우선순위가 있나요?

엄격한 우선순위는 없습니다. Claude가 대화 맥락에 따라 가장 적절한 방식을 선택합니다.

지원되는 이미지 형식은 무엇인가요?

PNG, JPG, JPEG, BMP, WebP 등을 지원합니다. PNG 또는 JPG를 권장합니다.

URL 이미지 다운로드 실패 시 어떻게 하나요?

URL이 공개적으로 액세스 가능한지 확인하십시오. 로그인이 필요한 서비스의 경우 로컬로 다운로드한 후 imagePath를 사용하십시오.

파일 업로드 설명

type이 "local"일 때, MCP Server는 다음을 수행합니다:

  1. 로컬 파일 읽기

  2. 사전 서명된 URL을 통해 TOS 객체 스토리지로 직접 업로드

  3. 최대 파일 크기: 100MB

문제 해결

"command not found: npx"

Node.js >= 18을 설치하십시오: https://nodejs.org/

"오류: --api-key를 제공하거나 API_KEY를 설정해야 합니다"

API Key가 누락되었습니다. 구성의 env.API_KEY를 확인하십시오.

MCP Server가 클라이언트에서 빨간색/오류로 표시됨

로그 확인:

  • Claude Desktop macOS: ~/Library/Logs/Claude/mcp*.log

  • Claude Desktop Windows: %APPDATA%\Claude\logs\mcp*.log

  • Cursor: Output 패널 > MCP

전역 설치 (선택 사항)

매번 npx를 사용하고 싶지 않은 경우:

npm install -g @avclabs.ai/media-mcp

그런 다음 구성에서 "command": "media-mcp"와 "args": ["--api-key", "your-api-key"]를 함께 사용하십시오.

License

MIT License - 자세한 내용은 LICENSE 파일을 참조하십시오.

Available Tools

4 tools
create_taskB

创建视频增强任务(异步)

支持两种上传方式:

  1. URL 上传:提供视频 URL

  2. 本地上传:提供本地文件路径,MCP Server 自动上传到 TOS 对象存储

参数说明:

  • video_source: 视频 URL 或本地文件路径

  • type: "url" 或 "local"

  • resolution: 目标分辨率

Inputs: video_source (required), type, resolution.

enhance_video_syncA

同步增强视频(阻塞等待完成)

支持两种上传方式:

  1. URL 上传:提供视频 URL

  2. 本地上传:提供本地文件路径,MCP Server 自动上传到 TOS 对象存储

参数说明:

  • video_source: 视频 URL 或本地文件路径

  • type: "url" 或 "local"

  • resolution: 目标分辨率

  • poll_interval: 轮询间隔(秒)

  • timeout: 超时时间(秒)

Inputs: video_source (required), type, resolution, poll_interval, +1 more.

get_task_statusA

查询视频增强任务状态

Inputs: task_id (required).

sam3_predictA

Analyze an image using the SAM3 segmentation API to generate inference results (masks, boxes, scores). The image can be provided in one of three ways:

  1. imagePath: Absolute path of a local image file (e.g. C:\Users\xxx\photo.png). Use this when the user provides a local file path.

  2. imageUrl: Publicly accessible URL of the image (e.g. https://example.com/photo.jpg). Use this when the user provides a web link.

  3. imageBase64: Base64-encoded image data. Use this when the user uploads or drags-and-drops an image as an attachment and no local path is available. In this case, encode the image content as base64 and pass it via this parameter. If the user mentions an uploaded image but does not provide a path, URL, or base64 data, ask the user for the local absolute path. Prompt must be in English. If the user provides Chinese or other non-English text, translate it to English before calling this tool.

Inputs: prompt (required), imagePath, imageUrl, imageBase64.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation2/5

    The first three tools are about video enhancement tasks with overlapping functionality (create_task and enhance_video_sync both appear to initiate enhancement), and the fourth tool (sam3_predict) is for image segmentation, a completely different domain. The descriptions are not clear enough to distinguish which tool to use for a given task, causing confusion.

    Naming Consistency3/5

    Tool names partially follow a verb_noun pattern (create_task, get_task_status), but 'enhance_video_sync' is awkward and 'sam3_predict' mixes model name with verb, introducing inconsistency.

    Tool Count4/5

    With 4 tools, the count is reasonable for a focused server, but the server actually combines two unrelated capabilities (video enhancement and image segmentation), making the scope unclear but the number itself is not extreme.

    Completeness2/5

    For video enhancement, there are create, sync enhance, and status query, but missing cancel, list, or delete operations. For image segmentation, only a single predict tool exists. The surface is incomplete for both domains.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers