Media Agent MCP

一个基于 Model Context Protocol (MCP) 的媒体处理服务器，提供强大的AI驱动的媒体处理工具。

🚀 功能特性

核心工具 (9个)

TOS存储 - 将内容保存为URL
视频拼接 - 拼接多个视频文件
视频帧提取 - 提取视频的最后一帧
Seedream图像生成 - 使用AI模型生成图像
Seedance视频生成 - 使用AI模型生成视频（支持lite和pro版本）
Seededit角色维持 - 保持主要角色的一致性
Seed1.6视觉语言模型 - 执行视觉任务工作流
图像选择器 - 从多个图像中选择最佳的一个
视频选择器 - 从多个视频中选择最佳的一个

AI模型支持

Seedream: 高质量图像生成
Seedance: 视频生成（支持文本生成视频、首帧生成视频、首尾帧生成视频）
Seededit: 图像编辑和角色一致性维护
Seed1.6: 多模态视觉语言理解

📋 系统要求

Python >= 3.12
支持的操作系统：macOS, Linux, Windows

🛠️ 安装

方法一：使用 UVX（推荐）

uvx media-agent-mcp

方法二：本地开发安装

1. 克隆仓库

git clone <repository-url>
cd media-agent-mcp

2. 安装依赖

使用 uv（推荐）：

uv sync

或使用 pip：

pip install -e .

3. 配置环境变量

复制环境变量模板并填写配置：

cp .env.template .env

编辑 .env 文件，填写以下必要配置：

# TOS存储配置
TOS_ACCESS_KEY=your_tos_access_key_here
TOS_SECRET_KEY=your_tos_secret_key_here
TOS_BUCKET_NAME=your_bucket_name_here
TOS_ENDPOINT=tos-ap-southeast-1.bytepluses.com
TOS_REGION=ap-southeast-1

# 火山引擎视觉智能SDK配置
VOLC_ACCESS_KEY=your_volcengine_access_key_here
VOLC_SECRET_KEY=your_volcengine_secret_key_here

# BytePlus ModelArk API配置
ARK_API_KEY=your_ark_api_key_here
ARK_BASE_URL=https://ark.ap-southeast.bytepluses.com

# AI模型端点配置
SEEDANCE_EP=seedance-1-0-lite
SEEDREAM_EP=seedream-1-0
SEEDEDIT_EP=seededit-3-0
VLM_EP=seed-1-6-chat

🚀 使用方法

启动MCP服务器

使用 UVX

uvx media-agent-mcp

使用 UV（本地开发）

uv run media-agent-mcp

使用stdio传输（默认）

media-agent-mcp

使用SSE传输

media-agent-mcp --transport sse --host 127.0.0.1 --port 8000

直接运行服务器文件

cd src
python -m media_agent_mcp.server

命令行选项

media-agent-mcp --help

可用选项：

--transport: 传输方式 (sse 或 stdio，默认: stdio)
--host: SSE传输的主机地址 (默认: 127.0.0.1)
--port: SSE传输的端口 (默认: 8000)
--version: 显示版本信息

与MCP客户端集成

Claude Desktop配置

在Claude Desktop的配置文件中添加：

{
  "mcpServers": {
    "media-agent": {
      "command": "uvx",
      "args": ["media-agent-mcp"]
    }
  }
}

VS Code MCP扩展配置

{
  "mcp.servers": {
    "media-agent": {
      "command": "uvx",
      "args": ["media-agent-mcp"]
    }
  }
}

🔧 API工具详细说明

1. 视频拼接工具

video_concat_tool(video_urls: list[str]) -> str

拼接多个视频URL并上传到TOS。

参数：

video_urls: 要按顺序拼接的视频URL列表

返回： JSON字符串，包含状态、数据和消息

示例：

result = video_concat_tool([
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4"
])

2. 视频帧提取工具

video_last_frame_tool(video_path: str) -> str

从视频文件中提取最后一帧并上传到TOS。

参数：

video_path: 视频文件路径或URL

返回： JSON字符串，包含状态、数据和消息

3. Seedream图像生成工具

seedream_generate_image_tool(
    prompt: str, 
    style: str = "realistic", 
    size: str = "1024x1024"
) -> str

使用Seedream AI模型生成图像。

参数：

prompt: 图像描述文本
style: 图像风格（realistic, artistic, cartoon等）
size: 图像尺寸（如"1024x1024"）

示例：

result = seedream_generate_image_tool(
    prompt="一只可爱的小猫坐在花园里",
    style="realistic",
    size="1024x1024"
)

4. Seedance视频生成工具

seedance_generate_video_tool(
    prompt: str = "", 
    first_frame_image: str = None,
    last_frame_image: str = None, 
    duration: int = 5,
    resolution: str = "720p", 
    ratio: str = "16:9"
) -> str

使用Seedance AI模型生成视频。

参数：

prompt: 视频描述文本（图像转视频时可选）
first_frame_image: 首帧图像的URL或base64
last_frame_image: 尾帧图像的URL或base64（可选）
duration: 视频时长（5或10秒）
resolution: 视频分辨率（480p, 720p, 1080p）
ratio: 宽高比（16:9, 4:3, 1:1, 3:4, 9:16, adaptive等）

示例：

# 文本生成视频
result = seedance_generate_video_tool(
    prompt="一只鸟在天空中飞翔",
    duration=5,
    resolution="720p"
)

# 首帧生成视频
result = seedance_generate_video_tool(
    first_frame_image="https://example.com/first_frame.jpg",
    duration=5
)

5. 其他工具

Seededit角色维持工具: 保持图像中主要角色的一致性
Seed1.6 VLM工具: 执行视觉语言任务
图像选择器: 从多个图像中选择最佳的一个
视频选择器: 从多个视频中选择最佳的一个
TOS保存工具: 将内容保存到TOS并返回URL

📁 项目结构

media-agent-mcp/
├── src/
│   └── media_agent_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP服务器主文件
│       ├── ai_models/             # AI模型模块
│       │   ├── __init__.py
│       │   ├── seedream.py        # 图像生成
│       │   ├── seedance.py        # 视频生成
│       │   ├── seededit.py        # 图像编辑
│       │   └── seed16.py          # 视觉语言模型
│       ├── video/                 # 视频处理模块
│       │   ├── __init__.py
│       │   └── processor.py       # 视频处理功能
│       ├── storage/               # 存储模块
│       │   ├── __init__.py
│       │   └── tos_client.py      # TOS客户端
│       └── media_selectors/       # 媒体选择器
│           ├── __init__.py
│           ├── image_selector.py  # 图像选择
│           └── video_selector.py  # 视频选择
├── .env.template                  # 环境变量模板
├── .gitignore                     # Git忽略文件
├── pyproject.toml                 # 项目配置
├── uv.lock                        # 依赖锁定文件
└── README.md                      # 项目文档

🔑 API密钥获取

TOS存储

访问 BytePlus TOS控制台
创建存储桶并获取访问密钥
记录访问密钥、秘密密钥和存储桶名称

ModelArk API

访问 BytePlus ModelArk控制台
获取API密钥
选择合适的模型端点

火山引擎视觉智能

访问火山引擎控制台
开通视觉智能服务
获取访问密钥和秘密密钥

🐛 故障排除

常见问题

相对导入错误

ImportError: attempted relative import with no known parent package

解决方案: 使用模块方式运行：

cd src
python -m media_agent_mcp.server

环境变量未设置 确保 .env 文件已正确配置所有必要的API密钥。

依赖安装问题

pip install --upgrade pip
pip install -e .

或使用uv：

uv sync --reinstall

TOS上传失败
- 检查TOS配置是否正确
- 确认存储桶权限设置
- 验证网络连接
AI模型调用失败
- 检查API密钥是否有效
- 确认模型端点配置
- 查看API配额和限制

📝 开发

开发环境设置

# 克隆仓库
git clone <repository-url>
cd media-agent-mcp

# 使用uv创建虚拟环境并安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows

运行测试

# 运行测试套件
uv run test_server.py

# 运行特定测试
python -m pytest tests/

构建和发布

# 构建包
uv build

# 发布到PyPI
uv publish

添加新工具

在相应模块中实现功能
在 server.py 中添加 @mcp.tool() 装饰器
添加类型注解和文档字符串
更新README文档
添加测试用例

代码规范

使用类型注解
遵循PEP 8代码风格
添加详细的文档字符串
包含错误处理
返回统一的JSON格式

📊 性能优化

使用异步处理提高并发性能
实现缓存机制减少重复计算
优化文件上传和下载流程
合理设置超时和重试机制

🔒 安全考虑

不要在代码中硬编码API密钥
使用环境变量管理敏感信息
验证输入参数防止注入攻击
限制文件上传大小和类型
定期更新依赖包

📄 许可证

MIT License

🤝 贡献

欢迎提交Issue和Pull Request！

贡献流程

Fork 仓库
创建功能分支
提交更改
添加测试
提交Pull Request

📞 支持

如有问题，请：

查看本文档的故障排除部分
搜索已有的Issues
提交新的Issue
联系开发团队

📈 版本历史

v0.1.0 (Alpha) - 初始版本，包含9个核心工具
v2.2.0 add subtitle and description to tools
v2.3.0 add audio and video merge
v2.4.0 omni human, tts, stack video
v2.5.0 add openai image edit
v2.6.0 add google image edit

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
- Python :: 3.12

Metadata

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
- Python :: 3.12

Release files for media-agent-mcp 2.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for media-agent-mcp 2.8.0
File	Size	Uploaded
media_agent_mcp-2.8.0.tar.gz	23.2 MB	Sep 9, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for media-agent-mcp 2.8.0
File	Interpreter	ABI	Platform	Reset
media_agent_mcp-2.8.0-py3-none-any.whl 23.2 MB Sep 9, 2025	Python 3	none	any	Details

Total release size: 46.4 MB

Release files / media_agent_mcp-2.8.0.tar.gz

Download URL	media_agent_mcp-2.8.0.tar.gz
Size	23.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`94aed7e26ffa5d3bf5f48be7725db79aabf233a2caf8d3404441e60a9f4e9505`
BLAKE2b-256 checksum How to use checksums	`50e08e0d17db98364d458571bb7f40a261f258066c44210441a3585f721f3400`
Upload date	Sep 9, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.14`

Release files / media_agent_mcp-2.8.0-py3-none-any.whl

Download URL	media_agent_mcp-2.8.0-py3-none-any.whl
Size	23.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`487d55072cc3694cc9e7eede77ed944a942ee238f96b1dcaa17aee6abfc58f76`
BLAKE2b-256 checksum How to use checksums	`9c5cbfac3b56337dc5f15cbe8e22b6eda9726848612f7f186698f093df9d9190`
Upload date	Sep 9, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.14`