media-mcp (Node.js)

Chinese | English

Video enhancement and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with a backend HTTP Server.

Features

Provides the following MCP Tools:

• create_task - Create a video enhancement task (supports URL or local file upload)

• get_task_status - Query task status

• enhance_video_sync - Synchronous video enhancement (blocks until completion)

• sam3_predict - SAM3 image segmentation (supports local path, URL, or Base64 image)

Related MCP server: Grok Imagine Video MCP Server

Prerequisites

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

• API Key (For authentication, please contact the service provider to obtain one)

Easy Installation (Recommended)

If your AI Agent has a defined MCP configuration path, simply copy and send the following sentence to the AI:

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

The AI will automatically:

1. Detect the MCP client you are using

2. Find the configuration file path

3. Write the correct configuration

4. Prompt you to restart the client

Manual Installation

No installation required; run directly in the MCP client configuration using npx.

1. Claude Code (CLI)

Run in Claude Code:

/mcp

Check the output for the configuration file path corresponding to "User MCPs", 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 the following content (replace your-api-key with your actual API Key):

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

After saving, run /mcp to verify if it loaded successfully.

2. Cursor

Go to Settings > 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

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 the client, confirm if the tools loaded successfully:

1. Or ask the AI directly: "What tools do you have available?"

2. You should see: create_task, get_task_status, enhance_video_sync, sam3_predict

Configuration Options

Custom Service URL

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

Or via command line arguments:

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

Usage Examples

Once configured, use natural language to tell the AI:

"Help me enhance this video to 1080p: https://example.com/video.mp4"

"Upscale the video.mp4 on my desktop to 2k quality"

The AI will automatically call the corresponding tool to complete the task.

"Help me analyze this image and find all objects in it: C:\Users\xxx\photo.png"

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

Provided Tools

create_task

Create a video enhancement task (asynchronous).

Return Value:

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

get_task_status

Query task status.

Return Value:

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

enhance_video_sync

Synchronous video enhancement (blocks until completion).

sam3_predict

Use the SAM3 segmentation API to analyze an image and generate inference results (masks, boxes, scores).

Parameters:

Image input (choose one of the three, one must be provided):

• imagePath (string): Absolute path to a local image. Supports common image formats (e.g., PNG, JPG, JPEG).

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

  • Use case: User explicitly provided a local file path

• imageUrl (string): Publicly accessible image URL.

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

  • Use case: Image is already online, user provided a link

  • Note: URL must be publicly accessible; links requiring login or signatures are not supported

• imageBase64 (string): Base64 encoded image data.

  • Example: "iVBORw0KGgoAAAANSUhEUgAA..."

  • Use case: User dragged or uploaded an image attachment, Agent encodes the image to base64 and passes it

  • Note: Base64 data for large images can be quite large, transmission time may be slightly longer

Other parameters:

• prompt (string, required): English text prompt used to specify the target object to segment in the image. For example, "person", "car", "a cat sitting on a sofa". Since the SAM3 model only accepts English prompts, it is recommended to pass English descriptions. If the user provides Chinese or other non-English text, the Agent will automatically translate it to English before calling.

Return:

After inference is complete, a JSON string is returned directly. The JSON contains the following three fields:

• masks: Two-dimensional array. Each element is a binary mask (values 0 or 1) with the same dimensions as the input image, used to mark the pixel-level location of the detected object in the image. The i-th mask in the array corresponds to the i-th detected object instance.

• boxes: Two-dimensional array. Each element is a bounding box coordinate in [x1, y1, x2, y2] format, representing the rectangular area of the detected object in the image. x1, y1 are the top-left coordinates, and x2, y2 are the bottom-right coordinates.

  Coordinate system explanation: The origin (0, 0) is the top-left corner of the image, the x axis increases to the right, and the y axis increases downwards, in pixels. For example, [120, 80, 300, 450] means the object area starts 120px from the left edge and 80px from the top edge, ending at 300px from the left edge and 450px from the top edge, with a width of x2 - x1 = 180px and a height of y2 - y1 = 370px.

• scores: One-dimensional array. Each element is the confidence score for the corresponding detection result, ranging from 0 to 1. A higher score indicates the model is more certain about the detection result.

Example of result JSON content:

{
  "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]
}

FAQ

Prompted that file cannot be found after dragging an attachment?

This is a known limitation of stdio MCP. When dragging or uploading attachments via the Agent interface, the file path is usually not automatically passed to the MCP Server.

Solution:

1. Provide the path as well (Recommended): After dragging the image, add the local absolute path of the image in the text:

   "Please process this image D:\photos\cat.jpg, find the cat in it"

2. Wait for automatic encoding: Claude may automatically encode the image to base64 and pass it. If successful, no further action is needed.

3. Answer path inquiry: If Claude asks for the image path, simply reply with the local absolute path.

Is there a priority for the three input methods?

There is no strict priority. Claude will automatically choose the most appropriate method based on the conversation context:

• You provided a local path → Use imagePath

• You provided a web link → Use imageUrl

• You dragged an attachment and there is no path → Try imageBase64

Which image formats are supported?

Common formats are supported: PNG, JPG, JPEG, BMP, WebP, etc. It is recommended to prioritize PNG or JPG.

What if URL image download fails?

Ensure the URL is publicly accessible and does not require login, cookies, or signatures. If the image is on a service that requires authentication (e.g., private S3 Bucket, image hosting requiring login), please download it locally first and use imagePath.

What if the Base64 image is too large?

If the image is very large (e.g., 4K resolution), the base64 encoded data will be very large, which may cause slow transmission. It is recommended to:

1. Use imagePath instead

2. Or compress the image before encoding

File Upload Instructions

When type is "local", the MCP Server will:

1. Read the local file

2. Upload directly to TOS object storage via a pre-signed URL

3. Maximum file size: 100MB

Troubleshooting

"command not found: npx"

Install Node.js >= 18: https://nodejs.org/

"Error: --api-key must be provided or API_KEY must be set"

API Key is missing, please check env.API_KEY in the configuration.

MCP Server shows red/error in client

Check logs:

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

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

• Cursor: Output panel > MCP

"TOS upload failed"

Usually due to a signature mismatch; please confirm that HTTP_API_BASE_URL and HTTP_API_KEY are correct and valid.

Global Installation (Optional)

If you don't want to use npx every time:

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

Then use "command": "media-mcp" with "args": ["--api-key", "your-api-key"] in the configuration.

License

MIT License - See LICENSE file for details