media-mcp (Node.js)

Deployment update (2026-09-06): the SAM3 source and release scripts are now maintained in sam3-http-server, rooted at /opt/ai/sam3. API schema candidate head is 20260906_0007. SAM3 production bootstrap and nine-tool E2E remain pending. See the four-project rollout.

English | 中文

A video enhancement, image enhancement/colorization/denoising, and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with backend HTTP Servers.

Release status (2026-09-06): npm latest is 0.2.1; that published artifact contains 5 tools (3 video + 2 SAM3) and its runtime metadata incorrectly reports 0.3.0. This repository is the unreleased 0.3.0 candidate, which fixes version consistency and adds 4 image tools plus an optional IMAGE_API_BASE_URL override. Image and video share the same public HTTP server and /enhance base URL; the candidate backend keeps their prepare concurrency, Redis queues, workers, and processing concurrency separate. The image routes now exist in candidate code but are not deployed or real-AI/TOS verified, so the image tools below are not a production npm capability until all 9 tools pass smoke tests and 0.3.0 is published.

Features

Provides the following MCP Tools:

Video Enhancement

• create_task - Create a video enhancement task (supports URL or local file upload)
• get_task_status - Query task status
• enhance_video_sync - Synchronously enhance video (blocking wait, truncated at ~50s by default)

Image Enhancement (unreleased 0.3.0 candidate)

• enhance_image_sync - Enhance image quality and optimize faces (supports URL or local file upload)
• colorize_image_sync - Colorize black-and-white photos (supports URL or local file upload)
• denoise_image_sync - Remove noise from images (supports URL or local file upload)
• get_image_task_status - Query image task status (for polling after sync timeout)

Image Segmentation (SAM3)

• sam3_predict - SAM3 image segmentation (supports local path, URL, or Base64 image)
• get_sam3_task_status - Query SAM3 task status (for polling after sync timeout)

Prerequisites

• Node.js >= 18 (check: node --version)
• API Key (required for authentication)

Lazy Install (Recommended)

If your AI Agent has a known MCP config path, just copy the line below and send it to your AI:

Install the npm package @avclabs.ai/media-mcp as an MCP server. My API Key is: sk-xxxxxxxx.

The AI will automatically:

1. Detect your MCP client
2. Find the config file path
3. Write the correct configuration
4. Prompt you to restart the client

Manual Install

No installation needed. Use npx directly in your MCP client config.

1. Claude Code (CLI)

Run in Claude Code:

/mcp

Check the output for the "User MCPs" section to find the config file path, then edit that file.

Common paths (if /mcp is unavailable):

• Windows: %USERPROFILE%\.claude.json
• macOS: ~/.claude.json
• Linux: ~/.claude.json
• Legacy/Alternative: ~/.claude/mcp.json

Paste this (replace your-api-key):

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

Save and run /mcp to verify it's loaded.

2. Cursor

Go to Settings > Tools & MCPs > Add New MCP Server:

• Name: video-enhancement
• Type: command
• Command:
  bash

  Copy

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

Or edit ~/.cursor/mcp.json:

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

Verify Installation

After restarting your client, check if the tools are available:

1. Or ask: "What tools do you have available?"
2. With the current npm latest=0.2.1, you should see create_task, get_task_status, enhance_video_sync, sam3_predict, and get_sam3_task_status.
3. After 0.3.0 is published, you should additionally see enhance_image_sync, colorize_image_sync, denoise_image_sync, and get_image_task_status.

Configuration Options

IMAGE_API_BASE_URL is implemented by the unreleased 0.3.0 candidate as an optional override. Production uses the shared /enhance service, so it should normally be omitted; the candidate then resolves image and video calls to the same base URL.

Custom Endpoint (0.3.0 candidate)

{
  "env": {
    "HTTP_API_BASE_URL": "https://your-media-endpoint.com",
    "API_KEY": "your-api-key",
    "SAM3_API_BASE_URL": "https://your-sam3-endpoint.com"
  }
}

Or via CLI args:

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

Run this command only after 0.3.0 is published. The optional --image-base-url remains available only for deployments that intentionally split the public image endpoint; npm 0.2.1 does not support it.

Recommended Workflow

This project provides both synchronous and asynchronous modes.

Because MCP Agents typically enforce a ~60-second timeout per tool call, tasks with longer processing times (video enhancement) are strongly recommended to use asynchronous mode:

Asynchronous Mode (Recommended)

Video Enhancement:

1. Call create_task to create a task → immediately get task_id
2. Wait a few seconds, then call get_task_status to query the status
3. If status is processing, continue waiting and repeat step 2
4. If status is completed, the task is done and the result contains video_url
5. If status is failed, the task failed and the result contains error_message

Synchronous Mode (Simple Scenarios)

Video Enhancement:

• Call enhance_video_sync → the server polls internally
• Defaults to a maximum wait of 50 seconds
• If completed within 50 seconds, returns the result directly
• If not completed within 50 seconds, returns task_id and instructions for the Agent to switch to get_task_status

Image Segmentation (SAM3):

• Call sam3_predict → the server polls internally
• Defaults to a maximum wait of 50 seconds (25 attempts × 2-second polling interval)
• If completed within 50 seconds, returns the segmentation result directly
• If not completed within 50 seconds, returns a truncation notice indicating the task is still processing

Usage Examples

Once configured, ask your AI agent naturally:

"Enhance this video to 1080p: https://example.com/video.mp4"

"Improve the quality of /Users/me/Desktop/video.mp4 to 2k"

"Enhance this image: https://example.com/photo.jpg"

"Colorize this black-and-white photo: /Users/me/Desktop/old_photo.png"

"Remove noise from this image: C:\Users\xxx\noisy.jpg"

"Analyze this image and find all objects: C:\Users\xxx\photo.png"

"Use SAM3 to segment this image, prompt: 'find all cars'"

The agent will automatically choose sync or async tools based on task complexity.

Provided Tools

Video Enhancement

create_task

Create an asynchronous video enhancement task.

Recommended for most use cases. Ideal for longer videos (over 10 seconds) to avoid timeouts and blocking the connection.

Returns:

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

get_task_status

Query video enhancement task status.

The returned status field can be: processing, completed, or failed. If status is processing, you need to wait a few seconds and call this tool again.

Returns:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "video_url": "https://...",
  "message": "Task is still processing, please check again later"
}

The message field only appears when status is processing, prompting the Agent to continue waiting.

enhance_video_sync

Synchronously enhance video (blocks until completion).

Best for short videos (estimated processing time < 1 minute). If the task is not completed within 50 seconds, the tool returns early with a task_id, and you need to use get_task_status to continue querying.