内容
# 视频分析 MCP 服务器
由 [Moonshot / Kimi API](https://platform.moonshot.cn/) 驱动的视觉 MCP 服务器。为使用纯文本模型的 MCP 客户端（如 Claude Code / Claude Desktop 中的 DeepSeek）带来图像和视频理解能力。
> 该项目是原 `video-analyzer-mcp` 的重构版本，用直接的 Moonshot OpenAI 兼容 API 调用替换了本地 `kimi` CLI 依赖。
## 功能特点
- 🖼️ **图像理解**，通过 Kimi K2.6 / K2.7 代码视觉模型
- 🎬 **视频分析**，附带结构化摘要
- 🧩 **特定场景工具**，灵感来自 [Z.AI GLM 视觉 MCP 服务器](https://docs.z.ai/devpack/mcp/vision-mcp-server)：
- `vision_ui_to_artifact` — 将 UI 截图转换为代码/规格/提示
- `vision_extract_text` — 代码、终端、文档的 OCR
- `vision_diagnose_error` — 分析错误截图并建议修复
- `vision_understand_diagram` — 解释架构/流程/UML/ER 图表
- `vision_analyze_data_viz` — 从图表和仪表盘中提取洞察
- `vision_ui_diff_check` — 比较前后截图
- `vision_analyze_image` — 通用图像问答
- `vision_analyze_video` — 视频摘要和关键时刻
- 🔌 **多种传输方式**：stdio、SSE、可流式 HTTP
- ⚙️ **简单配置**：仅需 `MOONSHOT_API_KEY`
## 要求
- Python 3.10+
- 一个 [Moonshot API 密钥](https://platform.moonshot.cn/)
## 快速安装
### macOS / Linux
```bash
bash install.sh
```
### Windows
```powershell
.\install.ps1
```
### Claude Code / Desktop（一行命令）
```bash
claude mcp add -s user video-analyzer \
--env MOONSHOT_API_KEY=your_api_key \
-- python C:/Users/unive/projects/video-analyzer-mcp/server.py
```
将 `C:/Users/unive` 替换为 macOS/Linux 上实际的主目录路径。
## 手动配置
在 Claude Desktop / Claude Code MCP 配置中添加：
```json
{
"mcpServers": {
"video-analyzer": {
"type": "stdio",
"command": "python",
"args": ["C:/Users/unive/projects/video-analyzer-mcp/server.py"],
"env": {
"MOONSHOT_API_KEY": "your_api_key",
"VISION_MODEL": "kimi-k2.7-code"
}
}
}
}
```
## 环境变量
| 变量名 | 默认值 | 描述 |
|--------|---------|-------------|
| `MOONSHOT_API_KEY` | — | **必填**。Moonshot API 密钥 |
| `VISION_MODEL` | `kimi-k2.7-code` | 要使用的视觉模型 |
| `VISION_BASE_URL` | `https://api.moonshot.ai/v1` | OpenAI 兼容的基准 URL |
| `VISION_TIMEOUT` | `300` | API 超时（秒） |
| `VISION_MAX_IMAGE_SIZE_MB` | `20` | 最大图像文件大小 |
| `VISION_MAX_VIDEO_SIZE_MB` | `100` | 最大视频文件大小 |
## 使用示例
在 Claude Code 或 Claude Desktop 中：
```
请对 /Users/me/screenshots/login.png 使用 vision_analyze_image 并描述布局。
```
```
对 /Users/me/screenshots/build_error.png 使用 vision_diagnose_error 以查找构建失败的原因。
```
## 开发
```bash
cd C:/Users/unive/projects/video-analyzer-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install pytest pytest-asyncio respx ruff
pytest
ruff check src tests server.py
```
## 使用 SSE 或流式 HTTP 运行
```bash
# SSE
python server.py --transport sse --port 8000
# 流式 HTTP
python server.py --transport streamable-http --port 8000
```
## 卸载
```bash
python install.py uninstall
```
## 文档
- [架构](docs/architecture.md)
- [工具参考](docs/tools.md)
- [开发指南](docs/development.md)
## 许可证
MIT
