media-mcp
OfficialThis server provides video enhancement and image segmentation capabilities via MCP tools.
create_task– Asynchronously create a video enhancement task by providing a video URL or local file path, with options for target resolution (480p,540p,720p,1080p,2k). Returns atask_idimmediately for later status polling.get_task_status– Query the status of a previously created video enhancement task using itstask_id. Returns the current status (processing,completed, orfailed), progress, and the final video URL upon completion.enhance_video_sync– Synchronously enhance a video, blocking until the task completes or a timeout is reached. Supports URL or local file input, resolution selection, configurable polling interval, and timeout. If the task doesn't finish in time, it returns thetask_idso you can follow up withget_task_status.sam3_predict– Run SAM3 image segmentation on an image provided via local file path, public URL, or base64-encoded data. Requires an English text prompt describing the target object(s). Returns segmentation masks, bounding boxes, and confidence scores for detected objects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@media-mcpenhance this video to 1080p: https://example.com/video.mp4"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 statusenhance_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:
Detect the MCP client you are using
Find the configuration file path
Write the correct configuration
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:
/mcpCheck the output for the configuration file path corresponding to "User MCPs", then edit that file.
Common paths (if /mcp is unavailable):
Windows:
%USERPROFILE%\.claude.jsonmacOS:
~/.claude.jsonLinux:
~/.claude.jsonLegacy/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-enhancementType:
commandCommand:
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:
Or ask the AI directly: "What tools do you have available?"
You should see:
create_task,get_task_status,enhance_video_sync,sam3_predict
Configuration Options
Variable Name | Required | Default Value | Description |
| Yes | - | API authentication key (shared by video enhancement and SAM3) |
| No |
| Video enhancement service interface URL |
| No |
| SAM3 service interface URL |
| No |
| Polling interval (ms) |
| No |
| Maximum polling attempts |
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:8001Usage 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).
Parameter | Type | Required | Default Value | Description |
| string | Yes | - | Video URL or local file path (URL must be publicly accessible; links requiring login or signatures are not supported) |
| string | No |
|
|
| string | No |
|
|
Return Value:
{
"success": true,
"task_id": "xxx",
"status": "wait"
}get_task_status
Query task status.
Parameter | Type | Required |
| string | Yes |
Return Value:
{
"success": true,
"task_id": "xxx",
"status": "completed",
"progress": 100,
"video_url": "https://..."
}enhance_video_sync
Synchronous video enhancement (blocks until completion).
Parameter | Type | Required | Default Value | Description |
| string | Yes | - | Video URL or local file path (URL must be publicly accessible; links requiring login or signatures are not supported) |
| string | No |
|
|
| string | No |
| Target resolution |
| number | No |
| Polling interval (seconds) |
| number | No |
| Timeout (seconds) |
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,y1are the top-left coordinates, andx2,y2are the bottom-right coordinates.Coordinate system explanation: The origin
(0, 0)is the top-left corner of the image, thexaxis increases to the right, and theyaxis 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 ofx2 - x1 = 180pxand a height ofy2 - 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:
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"Wait for automatic encoding: Claude may automatically encode the image to base64 and pass it. If successful, no further action is needed.
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
imagePathYou provided a web link → Use
imageUrlYou 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:
Use
imagePathinsteadOr compress the image before encoding
File Upload Instructions
When type is "local", the MCP Server will:
Read the local file
Upload directly to TOS object storage via a pre-signed URL
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*.logClaude Desktop Windows:
%APPDATA%\Claude\logs\mcp*.logCursor: 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-mcpThen use "command": "media-mcp" with "args": ["--api-key", "your-api-key"] in the configuration.
License
MIT License - See LICENSE file for details
Available Tools
4 toolscreate_taskB
创建视频增强任务(异步)
支持两种上传方式:
URL 上传:提供视频 URL
本地上传:提供本地文件路径,MCP Server 自动上传到 TOS 对象存储
参数说明:
video_source: 视频 URL 或本地文件路径
type: "url" 或 "local"
resolution: 目标分辨率
| Name | Required | Description | Default |
|---|---|---|---|
| video_source | Yes | 视频URL地址或本地文件路径(URL必须公网可访问,不支持需要登录或签名的链接) | |
| type | No | 上传类型:url=网络视频,local=本地文件 | url |
| resolution | No | 目标分辨率,默认720p | 720p |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It notes async behavior and TOS upload but omits side effects, permissions, failure modes, or rate limits. The description only partially discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three bullet points and front-loaded purpose. Every sentence earns its place, but structure could be slightly improved with clearer differentiation from siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input parameters well but lacks output schema explanation (e.g., task ID or status). With no annotations and multiple siblings, more context on post-creation steps would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description groups parameters and explains the two upload modes, but does not add new information beyond the schema's existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an async video enhancement task and distinguishes between two upload methods (URL and local). It uses specific verbs and resources, and is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each upload type (URL vs local) but does not explicitly guide when to use this async tool over its sync sibling (enhance_video_sync) or other tools like get_task_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
enhance_video_syncA
同步增强视频(阻塞等待完成)
支持两种上传方式:
URL 上传:提供视频 URL
本地上传:提供本地文件路径,MCP Server 自动上传到 TOS 对象存储
参数说明:
video_source: 视频 URL 或本地文件路径
type: "url" 或 "local"
resolution: 目标分辨率
poll_interval: 轮询间隔(秒)
timeout: 超时时间(秒)
| Name | Required | Description | Default |
|---|---|---|---|
| video_source | Yes | 视频URL地址或本地文件路径(URL必须公网可访问,不支持需要登录或签名的链接) | |
| type | No | 上传类型:url=网络视频,local=本地文件 | url |
| resolution | No | 目标分辨率,默认720p | 720p |
| poll_interval | No | 轮询间隔(秒),默认5 | |
| timeout | No | 超时时间(秒),默认600 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It explicitly states 'blocking wait for completion', explains the automatic upload of local files to TOS storage, and mentions polling parameters, giving good transparency. It does not mention side effects, but given the nature, none are expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and clear categorization of upload methods and parameters. Every sentence serves a purpose, and there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the blocking nature, upload methods, and all parameters thoroughly. It lacks an explicit description of the return value, but given the synchronous nature, it likely returns the enhanced video. Overall, it is fairly complete for a tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context beyond the schema, such as the automatic upload process for local files and that URLs must be publicly accessible. This extra information enhances understanding of parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to enhance video synchronously, with a blocking wait. It details two upload methods (URL and local), distinguishing it from sibling tools that handle different operations like task creation or status checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two upload methods and the blocking nature, implicitly indicating when to use the tool. However, it does not explicitly contrast with siblings like create_task (likely async) or provide when-not-to-use guidance, making usage guidelines less explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_task_statusA
查询视频增强任务状态
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | 任务ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the purpose without disclosing any behavioral traits such as polling requirements, rate limits, or expected response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words; efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status query with one parameter, the description is mostly complete but could benefit from mentioning possible return statuses or output format since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no additional meaning beyond what is already in the input schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'query' and the resource 'video enhancement task status', distinguishing from sibling tools 'create_task' and 'enhance_video_sync' which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the context of sibling tools implies it is for checking status after creation or enhancement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
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.
imageUrl: Publicly accessible URL of the image (e.g. https://example.com/photo.jpg). Use this when the user provides a web link.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| imagePath | No | Absolute path of a local image file (e.g. C:\\Users\\xxx\\photo.png) | |
| imageUrl | No | Publicly accessible URL of the image to process | |
| imageBase64 | No | Base64-encoded image data. Use this when the image is provided as an attachment without a local path | |
| prompt | Yes | Text prompt for mask generation. Must be in English. If the user provides Chinese or other non-English text, translate it to English before calling this tool |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it calls an external API and generates masks, boxes, scores. However, it lacks details on potential side effects, authentication, error handling, or rate limits. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points, front-loading the main purpose. Every sentence serves a purpose, explaining input methods and prompt requirements without redundancy. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does (segmentation analysis), how to provide input (three methods), and what outputs are generated (masks, boxes, scores). Even without an output schema, it gives sufficient information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant value by explaining usage contexts for each image parameter and specifying that the prompt must be in English, requiring translation if needed. This goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze an image using the SAM3 segmentation API to generate inference results (masks, boxes, scores).' This specifies the verb (analyze), resource (image via SAM3 API), and output, effectively distinguishing it from siblings like create_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each image input method (imagePath, imageUrl, imageBase64) and includes instructions for handling non-English prompts. However, it does not explicitly mention when not to use this tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.0- First observed
create_task - First observed
enhance_video_sync - First observed
get_task_status - First observed
sam3_predict
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Wan AI video generation
MCP server for Google Veo AI video generation
MCP server for MiniMax H3 multimodal video generation
MCP server for Luma Dream Machine AI video generation
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for 4K video generation using Google VEO 3.1 — text-to-video, image-to-video, video extension, and frame interpolation.1MIT
- AlicenseAqualityBmaintenanceMCP server for generating, editing, and batch processing videos using xAI's Grok Imagine Video API, with support for text-to-video, image-to-video, and video editing via natural language prompts.445 npm1MIT
- AlicenseAqualityCmaintenanceMCP server for AI-powered media generation: images, videos, audio, and upscaling using 99 AI models.6MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server enabling video processing via natural language: transcription with Whisper, segment cutting with FFmpeg, and file management.MIT