内容
# Kaltura MCP Server
一个模型上下文协议（MCP）服务器，提供安全的只读工具来管理Kaltura API操作。该服务器使AI助手能够安全地搜索、发现和分析Kaltura媒体内容。
## 功能
- **Media Discovery**：搜索和浏览具有高级过滤功能的媒体条目
- **Content Analysis**：访问字幕、文本记录和附件内容
- **Category Management**：浏览和探索内容类别
- **Analytics**：检索观看分析和性能指标
- **Secure Access**：具有全面输入验证的只读操作
- **Session Management**：具有可配置过期的自动会话处理
## 安装
1. 克隆此存储库：
```bash
git clone https://github.com/zoharbabin/kaltura-mcp.git
cd kaltura-mcp
```
2. 安装依赖项：
```bash
pip install -e .
```
## 使用模式
此服务器支持两种部署模式：
### 🔧 本地 MCP Server (Stdio Mode)
**最适合：**个人使用、直接Claude Desktop集成、开发
### 🌐 远程 MCP Server (HTTP/SSE Mode)
**最适合：**托管服务、多用户、生产部署
---
## 本地 MCP Server设置 (Claude Desktop)
### 步骤 1：安装包
```bash
pip install kaltura-mcp
```
### 步骤 2：设置环境配置
**🔒 安全方法（推荐）**：使用交互式设置脚本：
```bash
# Navigate to your project directory
cd /path/to/kaltura-mcp
# Run the interactive setup
python setup_env.py
```
该脚本将指导您完成：
1. 选择stdio（本地）或远程模式
2. 安全地输入您的Kaltura凭据
3. 生成具有适当权限（600）的`.env`文件
4. 提供确切的Claude Desktop配置
**📋 手动方法**：复制并编辑示例文件：
```bash
# Copy the example file
cp .env.example .env
# Edit with your credentials
# - For stdio mode: Only fill in KALTURA_* variables
# - For remote mode: Fill in JWT_SECRET_KEY, OAUTH_*, and SERVER_* variables
nano .env
# Set secure permissions
chmod 600 .env
```
### 步骤 3：获取您的Kaltura凭据
您需要从您的Kaltura帐户中获取这些凭据：
- **Service URL**：您的Kaltura服务器URL（通常是`https://cdnapisec.kaltura.com`）
- **Partner ID**：您的数字合作伙伴ID（在KMC → Settings → Integration Settings中找到）
- **Admin Secret**：您的API管理员密钥（在KMC → Settings → Integration Settings中找到）
- **User ID**：您的Kaltura用户ID（通常是您的电子邮件或`admin`）
### 步骤 4：配置Claude Desktop
打开您的Claude Desktop配置文件：
**macOS**：`~/Library/Application\ Support/Claude/claude_desktop_config.json`
**Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
**🔒 安全配置（.env文件中的凭据）**：
```json
{
"mcpServers": {
"kaltura": {
"command": "/full/path/to/kaltura-mcp"
}
}
}
```
**重要提示**：
- 将`/full/path/to/kaltura-mcp`替换为您的kaltura-mcp命令的实际路径（使用`which kaltura-mcp`找到它）
- `.env`文件由服务器从项目目录自动加载
- `setup_env.py`脚本将自动检测并提供正确的命令路径
### 步骤 5：重启Claude Desktop
保存配置文件后，完全重启Claude Desktop以使更改生效。
### 步骤 6：测试集成
在Claude Desktop中，尝试询问：
- "Search for recent Kaltura videos"
- "List my Kaltura categories"
- "Find videos about [topic] in my Kaltura account"
### 故障排除本地设置
**问题**：找不到`kaltura-mcp`命令
- **解决方案**：确保您已使用`pip install kaltura-mcp`安装，并且该命令在您的PATH中
**问题**："Error: Missing required environment variables"
- **解决方案**：
1. 检查`.env`文件是否存在于您的项目目录中
2. 验证文件权限：`ls -la .env`（应显示`-rw-------`）
3. 确保所有必需的Kaltura凭据都在`.env`文件中设置
**问题**："Invalid credentials" 或 "Authentication failed"
- **解决方案**：
1. 在Kaltura KMC → Settings → Integration Settings中验证您的凭据
2. 检查`.env`文件中是否存在拼写错误或多余的空格
3. 运行`python setup_env.py`以重新创建配置
**问题**：Claude Desktop不显示MCP服务器
- **解决方案**：
1. 使用JSON验证器检查配置文件语法
2. 验证命令路径是否正确（使用`which kaltura-mcp`）
3. 完全重启Claude Desktop
4. 检查Claude Desktop日志中的错误消息
**问题**：".env file not found" 错误
- **解决方案**：
1. 从您的项目目录运行`python setup_env.py`
2. 确保`.env`文件与服务器代码位于同一目录中
3. 检查文件权限：`ls -la .env`（应显示`-rw-------`）
**✅ 安全优势：**
- ✅ **安全文件权限**（600 - 仅所有者）
- ✅ **默认情况下被Git忽略**（不会被提交）
- ✅ **本地项目目录**（易于管理）
- ✅ **标准.env模式**（开发人员熟悉）
- ✅ **配置文件中没有凭据**（提高了安全性）
---
## 远程 MCP Server设置
### 配置
对于远程/托管部署，需要额外的环境变量：
```bash
cp .env.example .env
# Configure remote server settings
```
**必需的环境变量：**
- `JWT_SECRET_KEY`：用于JWT令牌签名的强密钥（⚠️ **对安全至关重要**）
- `OAUTH_REDIRECT_URI`：OAuth回调URL（例如，`https://your-domain.com/oauth/callback`）
- `SERVER_HOST`：服务器绑定地址（默认值：`0.0.0.0`）
- `SERVER_PORT`：服务器端口（默认值：`8000`）
**可选环境变量：**
- `SERVER_RELOAD`：在开发中启用自动重新加载（默认值：`false`）
- `OAUTH_CLIENT_ID`：自定义OAuth客户端ID
- `OAUTH_CLIENT_SECRET`：自定义OAuth客户端密钥
### 运行远程服务器
```bash
# Using the installed command
kaltura-mcp-remote
# Or using Python module
python -m kaltura_mcp.remote_server
```
远程服务器提供：
- 用于MCP协议的**HTTP/SSE传输**
- 用于安全凭据管理的**基于JWT的身份验证**
- 用于用户友好设置的**基于Web的授权**流程
- 用于作为服务托管的**多租户支持**
### 可用工具
1. **get_media_entry** - 获取有关特定媒体条目的详细信息
- 参数：entry_id（必需）
2. **list_categories** - 列出和搜索内容类别
- 参数：search_text, limit
3. **Analytics Tools** - 具有目标驱动功能的综合分析套件：
- **get_analytics** - 用于报告和分析的常规分析数据
- **get_analytics_timeseries** - 针对图表优化的时间序列数据
- **get_video_retention** - 详细的观看者保留分析，贯穿整个视频
- **get_realtime_metrics** - 每约30秒更新一次的实时分析
- **get_quality_metrics** - 体验质量（QoE）和流媒体性能
- **get_geographic_breakdown** - 基于位置的分析，具有各种粒度
- **list_analytics_capabilities** - 发现所有可用的分析功能
- 有关详细用法，请参见[Analytics Guide](docs/KALTURA_ANALYTICS_GUIDE.md)
4. **get_download_url** - 获取媒体文件的直接下载URL
- 参数：entry_id（必需），flavor_id
5. **get_thumbnail_url** - 获取具有自定义尺寸的视频缩略图/预览图像URL
- 参数：entry_id（必需），width，height，second
6. **search_entries** - 使用智能排序和过滤搜索和发现媒体条目
- 参数：query（必需），search_type，match_type，specific_field，boolean_operator，include_highlights，custom_metadata，date_range，max_results，sort_field，sort_order
7. **list_caption_assets** - 列出媒体条目的可用字幕
- 参数：entry_id（必需）
8. **get_caption_content** - 获取字幕内容和下载URL
- 参数：caption_asset_id（必需）
9. **list_attachment_assets** - 列出媒体条目的附件资产
- 参数：entry_id（必需）
10. **get_attachment_content** - 获取附件内容详细信息并将内容下载为base64
- 参数：attachment_asset_id（必需）
### 提示
服务器提供智能提示，以指导用户完成复杂的工作流程：
1. **analytics_wizard** - 用于创建综合分析报告的交互式指南
```
Arguments:
- analysis_goal: What to analyze (e.g., "video performance", "viewer engagement", "geographic reach")
- time_period: Time range (e.g., "today", "yesterday", "last_week", "last_month")
```
2. **content_discovery** - 用于查找媒体的自然语言搜索助手
```
Arguments:
- search_intent: What you're looking for in natural language
- include_details: Whether to fetch captions/attachments (yes/no)
```
3. **accessibility_audit** - 内容可访问性合规性检查器
```
Arguments:
- audit_scope: What to audit ("all", "recent", "category:name", or entry_id)
```
4. **retention_analysis** - 创建综合保留分析报告
```
Arguments:
- entry_id: Video to analyze (e.g., "1_3atosphg") [required]
- time_period: Months of data to analyze (default: "12")
- output_format: "interactive" (HTML) or "markdown" (default: "interactive")
```
### 资源
服务器将常用数据公开为缓存资源：
1. **kaltura://analytics/capabilities** - 完整的分析文档
- 所有60多种报告类型及其说明
- 可用的指标和维度
- 针对不同用例的最佳实践
- 缓存30分钟
2. **kaltura://categories/tree** - 具有条目计数的类别层次结构
- 完整的类别树结构
- 每个类别的条目计数
- 父子关系
- 缓存30分钟
3. **kaltura://media/recent/{count}** - 最近的媒体条目
- 将{count}替换为条目数（例如，kaltura://media/recent/20）
- 最多100个条目
- 包括基本元数据
- 缓存5分钟
---
## 远程 MCP Server（高级）
### 用户授权流程
1. **服务器部署**：将远程服务器部署到您的托管环境
2. **用户授权**：用户访问`https://your-server.com/oauth/authorize`
3. **凭据输入**：用户通过Web表单安全地输入其Kaltura凭据
4. **令牌生成**：服务器生成带有加密凭据的JWT令牌
5. **客户端配置**：用户将服务器URL和令牌添加到其MCP客户端
### 远程设置的分步指南
#### 1. 生成安全JWT密钥
```bash
# Generate a strong secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
#### 2. 配置环境
```bash
# Set in your .env file or environment
JWT_SECRET_KEY=your-generated-secret-key-here
OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```
#### 3. 部署服务器
**选项A：直接Python**
```bash
kaltura-mcp-remote
```
**选项B：Docker**
```bash
docker-compose up -d
```
**选项C：使用Gunicorn进行生产（可选）**
```bash
# Install gunicorn separately if needed for production
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker kaltura_mcp.remote_server:app
```
#### 4. 用户入门
将用户发送到：`https://your-server.com/oauth/authorize?response_type=code&client_id=kaltura-mcp&redirect_uri=https://your-server.com/oauth/callback&state=user123`
#### 5. 客户端配置
**对于Claude Desktop（远程模式）：**
将远程服务器与Claude Desktop一起使用的最简单方法是通过代理客户端：
```json
{
"mcpServers": {
"kaltura-remote": {
"command": "kaltura-mcp-proxy",
"env": {
"KALTURA_REMOTE_SERVER_URL": "https://your-server.com/mcp/messages",
"KALTURA_REMOTE_ACCESS_TOKEN": "your-jwt-token-from-authorization-flow"
}
}
}
}
```
代理客户端（`kaltura-mcp-proxy`）充当本地stdio MCP服务器，该服务器将请求转发到您的远程服务器。这提供了与Claude Desktop的最佳兼容性。
**对于自定义MCP客户端：**
```javascript
// HTTP transport with authentication
const transport = new HTTPTransport({
baseUrl: "https://your-server.com/mcp/messages",
headers: {
"Authorization": "Bearer user-jwt-token-here"
}
});
```
### 分析文档
MCP服务器提供了一个全面的分析套件，其中包含针对不同用例优化的目标驱动功能：
**专用分析功能：**
- **get_analytics**：以表格格式提供的综合报告数据，用于详细分析
- **get_analytics_timeseries**：针对图表和可视化优化的时间序列数据
- **get_video_retention**：详细的观看者保留曲线，准确显示观看者在哪里退出
- **get_realtime_metrics**：每约30秒更新一次的实时分析，用于监视
- **get_quality_metrics**：用于流媒体性能的体验质量（QoE）指标
- **get_geographic_breakdown**：在国家/地区，区域或城市级别上基于位置的分析
**分析功能：**
- 60多种报告类型，涵盖内容，用户，地理位置，平台等
- 用于自定义分析和可视化的原始数据访问
- 智能见解，包括退出点和参与模式
- 支持按日期范围，类别，用户和维度进行过滤
有关全面的文档，请参见：
- [Analytics Guide](docs/KALTURA_ANALYTICS_GUIDE.md) - 所有分析功能的完整参考
- [Analytics Examples](examples/analytics_examples.py) - 代码示例和可视化
### 安全注意事项
#### 生产部署
- **使用HTTPS**：始终使用TLS/SSL证书进行部署
- **安全JWT密钥**：使用加密强度高的密钥（32+字节）
- **环境安全**：切勿将密钥提交到版本控制
- **网络安全**：在适当的地方使用防火墙和VPN访问
- **定期更新**：保持依赖项更新以获取安全补丁
#### JWT令牌安全
- **令牌到期**：令牌默认在24小时后到期
- **凭据加密**：Kaltura凭据在JWT有效负载中加密
- **范围限制**：令牌仅限于只读Kaltura操作
- **撤销**：重启服务器以使所有现有令牌无效
#### 基础设施
```bash
# Example nginx configuration for production
server {
listen 443 ssl;
server_name your-kaltura-mcp.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### Docker部署
**docker-compose.yml用于生产：**
```yaml
version: '3.8'
services:
kaltura-mcp:
build: .
ports:
- "8000:8000"
environment:
- JWT_SECRET_KEY=${JWT_SECRET_KEY}
- OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback
- SERVER_HOST=0.0.0.0
- SERVER_PORT=8000
restart: unless-stopped
volumes:
- ./logs:/app/logs
labels:
- "traefik.enable=true"
- "traefik.http.routers.kaltura-mcp.rule=Host(\`your-domain.com\`)"
- "traefik.http.routers.kaltura-mcp.tls=true"
```
### 监控和日志记录
远程服务器提供内置的日志记录，可以通过以下方式进行监控：
- **运行状况检查**：`GET /`返回服务器状态
- **指标**：通过Docker卷或服务器日志访问日志
- **错误跟踪**：配置外部错误跟踪服务
### 重要的安全说明
#### 本地模式安全（推荐）
- ✅ **直接配置** - 在Claude Desktop中直接配置凭据
- ✅ **MCP标准合规性** - 客户端通过环境变量将凭据传递给服务器
- ✅ **进程隔离** - MCP服务器在具有有限范围的隔离进程中运行
- ✅ **无网络暴露** - 与Kaltura的直接API通信
- ✅ **本地凭据存储** - 凭据永远不会离开您的计算机
- ✅ **安全传输** - 凭据安全地传递到MCP服务器进程
#### 远程模式安全
- ✅ **凭据加密** - Kaltura凭据在JWT令牌中加密
- ✅ **令牌到期** - 自动24小时令牌到期
- ✅ **TLS加密** - 生产环境需要HTTPS
- ⚠️ **服务器信任** - 您必须信任远程服务器运营商
- ⚠️ **凭据传输** - 凭据已发送到远程服务器（已加密）
#### 生产清单
- [ ] 使用带有有效证书的HTTPS
- [ ] 生成强JWT密钥（32+字节）
- [ ] 配置安全环境变量
- [ ] 设置适当的日志记录和监控
- [ ] 实施速率限制（nginx/cloudflare）
- [ ] 定期安全更新
- [ ] 备份和灾难恢复计划
### 部署架构
#### 个人使用（推荐）
```
Claude Desktop ←→ Local MCP Server ←→ Kaltura API
```
#### 小团队
```
Claude Desktop ←→ Proxy Client ←→ Remote MCP Server ←→ Kaltura API
```
#### 企业
```
Multiple Clients ←→ Load Balancer ←→ Multiple MCP Servers ←→ Kaltura API
↓
Redis/Database
```
## 文档
- [Analytics Guide](docs/KALTURA_ANALYTICS_GUIDE.md) - 分析功能的综合指南
- [Prompts and Resources](docs/PROMPTS_AND_RESOURCES.md) - MCP提示和资源的详细文档
- [API Documentation](https://developer.kaltura.com/) - 官方Kaltura API文档
## 开发
### 运行测试
```bash
pytest
```
### 代码格式化
```bash
black src/
ruff check src/
```
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器