ZDF 媒体库 MCP 服务器
概述
ZDF Mediathek MCP服务器是一个独立的 模型上下文协议(MCP) 服务器
为人工智能助手提供对ZDF Mediatek API的访问。它支持自然语言搜索和检索
德国公共广播内容来自ZDF(Zweites Deutsches Fernsehen)。
该服务器可以与任何兼容MCP的AI客户端独立使用,包括Claude Desktop、GitHub Copilot、VS
代码、IntelliJ IDEA等。
运输支持: 支持流式HTTP(默认)和Stdio传输。一次只能有一个传输处于活动状态。使用 stdio 启用stdio传输的Spring配置文件(集 spring.ai.mcp.server.stdio=true 并禁用控制台输出)。
主要特点
- 🔍 内容搜索:按标题、主题或描述搜索ZDF Mediathek内容
- 📅 广播时间表:检索所有ZDF频道的电视节目时间表
- 📺 当前广播:获取ZDF频道当前播放的节目
- 🐳 Docker就绪:预先配置Docker镜像,便于部署
- 🔌 MCP兼容:适用于所有兼容MCP的AI客户端
- 🌐 柔性运输:流式HTTP(默认/生产)或Stdio(本地开发)
- 📊 综合录井:OAuth2和API请求的详细调试日志记录
MCP工具参考
服务器提供以下MCP工具:
| 工具 | 说明 | 关键参数 |
|---|---|---|
search_content |
在ZDF Mediathek中搜索内容 | query (字符串,必填) |
limit (数字,可选,默认值:5)|
get_broadcast_schedule · 获取特定频道和日期的电视节目表 · from (字符串,必填,ISO 8601)
to (字符串,必填,ISO 8601)
tvService (字符串,可选)
limit (数字,可选,默认值:10)|
get_current_broadcast · 获取频道上当前正在播放的节目 · tvService (字符串,必填)
limit (数字,可选,默认值:10)|
list_brands · 列出ZDF Mediathek中的所有电视品牌/系列 · limit (数字,可选,默认值:10)
list_series · 列出ZDF Mediathek中可用的所有系列 · limit (数字,可选,默认值:4)
list_seasons · 列出ZDF Mediathek中可用的所有季节 · limit (数字,可选,默认值:4)
get_series_episodes · 获取特定系列的剧集 · seriesName (字符串,必填)
limit (数字,可选,默认值:10)
注意:季节过滤尚未实现 |
工具使用示例
搜索内容:```json
{
"tool": "search_content",
"arguments": {
"query": "Tatort",
"limit": 5
}
}
**获取广播时间表:**```json
{
"tool": "get_broadcast_schedule",
"arguments": {
"from": "2025-12-27T00:00:00+01:00",
"to": "2025-12-27T23:59:59+01:00",
"tvService": "ZDF",
"limit": 10
}
}
获取当前广播:```json
{
"tool": "get_current_broadcast",
"arguments": {
"tvService": "ZDFneo",
"limit": 10
}
}
## 使用AI客户端
### 先决条件
1. **ZDF API证书**:获取OAuth2凭据
从 ZDF开发者门户
1. **码头工人**:在您的系统上安装Docker
### MCP传输类型
此服务器支持 **两种运输方式** (一次只有一个活动):
#### 1.流式HTTP传输(默认)
最适合:生产、远程访问、多个客户端
**默认情况下处于活动状态。** 服务器在正常启动时使用HTTP传输运行。
**端点:** `http://localhost:8080/`
**Docker:**```bash
docker run -d --name zdf-mcp \
-p 8080:8080 \
--restart unless-stopped \
-e ZDF_CLIENT_ID=your-client-id \
-e ZDF_CLIENT_SECRET=your-secret \
ghcr.io/nicklas2751/zdfmediathek-mcp:latest
MCP客户端配置:```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"type": "streamable-http",
"url": "http://localhost:8080"
}
}
}
**优势:**
- 服务器独立运行
- 多个客户端可以同时连接
- 可以远程访问
- 更适合调试(持久日志)
**健康检查端点:**
- 生活: `http://localhost:8080/actuator/health/liveness`
- 准备就绪: `http://localhost:8080/actuator/health/readiness`
- 一般健康: `http://localhost:8080/actuator/health`
#### 2.标准运输
最适合:本地开发、单用户、IDE集成
MCP客户端自动启动并管理Docker容器。容器通过stdin/stdout进行通信。
**激活方式:** 弹簧轮廓 `stdio` (推荐)或 `SPRING_AI_MCP_SERVER_STDIO=true`
这 `stdio` 轮廓:
- 启用stdio传输(`spring.ai.mcp.server.stdio=true`)
- 禁用控制台输出(横幅、日志),以保持MCP的stdin/stdout干净
- 将日志重定向到文件(`/tmp/zdfmediathek-mcp.log`)
**配置:**```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
注: Docker镜像预先配置了buildpack设置,可以最大限度地减少干净stdio通信的启动输出。
优势:
- 无需手动管理服务器
- MCP客户端管理的容器生命周期
- 单用户设置更简单
- 客户端关闭时自动清理
> 注: 启用stdio后,HTTP传输将自动禁用。一次只能有一个传输处于活动状态。
拟人克劳德桌面
运输: Stdio(由Claude Desktop管理的Docker)
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
配置示例:```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
**用途:**
1. 将配置添加到您的 `claude_desktop_config.json`
1. 重新启动克劳德桌面
1. Claude将在需要时自动启动Docker容器(stdio传输)
1. 问克劳德:“在ZDF媒体中心寻找泰特”
### GitHub Copilot命令行界面
**运输:** Stdio(由Copilot CLI管理的Docker)
**先决条件:**```bash
# Install GitHub Copilot CLI (if not already installed)
gh extension install github/gh-copilot
设置:
在中配置MCP服务器 ~/.config/github-copilot/mcp-servers.json:```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
**用途:**```bash
copilot "What's on ZDF tonight?"
copilot "Search for Tatort episodes"
VS代码与GitHub Copilot
运输: Stdio(由VS Code管理的Docker)
扩展要求:
- GitHub Copilot扩展
- VS代码1.99或更高版本
配置(.vcode/mcp.json或全局设置.json):```json
{
"servers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
**用途:**
1. 在VS Code中打开Copilot聊天
1. 选择“代理”模式
1. 单击工具图标查看可用的MCP服务器
1. 问:“在ZDF Mediathek中搜索Tatort”
### IntelliJ IDEA与GitHub Copilot
**运输:** Stdio(由IntelliJ管理的Docker)
**插件要求:**
- GitHub复制插件
- IntelliJ IDEA 2024.3或更高版本
**配置:**
1. 在IntelliJ IDEA中,打开GitHub Copilot聊天窗口
1. 点击 **“+添加更多工具”** 在聊天窗口的底部
1. 这将打开 `mcp.json` 配置文件(通常位于 `~/.config/github-copilot/intellij/mcp.json`)
1. 添加ZDF Mediathek MCP服务器配置:```json
{
"servers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
- 保存文件
- 在IntelliJ中重新启动GitHub Copilot服务(如果需要)
用途:
- 在IntelliJ中打开GitHub Copilot聊天
- ZDF Mediathek工具应出现在可用工具列表中
- 问:“在ZDF Mediathek中搜索Tatort”
基洛代码
运输: Stdio(由Kilo Code管理的Docker)
配置:
您可以在全局设置或项目级别进行配置:
选项A:全局配置(mcp_sesets.json):
- 点击⚙️ Kilo Code窗格中的图标→ “MCP服务器”选项卡
- 点击“编辑全局MCP”
- 添加配置:```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
},
"alwaysAllow": ["search_content", "get_broadcast_schedule", "get_current_broadcast", "list_brands", "list_series", "list_seasons"],
"disabled": false
}
}
}
**选项B:项目级配置(.kilocode/mcp.json):**
与上述配置相同,保存在 `.kilocode/mcp.json` 在您的项目根目录中。
**用途:**
1. 在Kilo Code聊天界面中键入您的请求
1. Kilo Code将自动检测并使用ZDF Mediathek MCP工具
1. 问:“ZDF目前有什么?”
### 其他MCP客户端
对于任何兼容MCP的客户端:
**选项1:标准传输(通过Docker)**```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "SPRING_PROFILES_ACTIVE=stdio",
"-e", "ZDF_CLIENT_ID",
"-e", "ZDF_CLIENT_SECRET",
"ghcr.io/nicklas2751/zdfmediathek-mcp:latest"
],
"env": {
"ZDF_CLIENT_ID": "your-client-id",
"ZDF_CLIENT_SECRET": "your-secret"
}
}
}
}
选项2:流式HTTP传输
- 启动服务器:```bash
docker run -d --name zdf-mcp \
-p 8080:8080 \
-e ZDF_CLIENT_ID=your-client-id \
-e ZDF_CLIENT_SECRET=your-secret \
ghcr.io/nicklas2751/zdfmediathek-mcp:latest
1. 配置您的客户端:```json
{
"mcpServers": {
"zdfmediathek-mcp": {
"type": "streamable-http",
"url": "http://localhost:8080"
}
}
}
开发设置
先决条件
- JDK 21或更高版本
- Gradle 8+(包括包装)
- Docker(用于容器化部署)
从源代码构建```bash
Clone repository
git clone https://github.com/Nicklas2751/zdfmediathek-mcp
cd zdfmediathek-mcp
Build project
./gradlew build
Run tests
./gradlew test
Run locally (Spring Boot)
./gradlew bootRun
Or with environment variables
ZDF_CLIENT_ID=your-id ZDF_CLIENT_SECRET=your-secret ./gradlew bootRun
### 配置
**环境变量:**
|变量|必填|描述|示例|
|---------------------|----------|-------------------------------|------------------|
| `ZDF_CLIENT_ID` |是|ZDF API的OAuth2客户端ID| `abc123...` |
| `ZDF_CLIENT_SECRET` |是|OAuth2客户端密码| `xyz789...` |
| `SERVER_PORT` |否|服务器端口| `8080` (默认)|
**应用程序配置** (`src/main/resources/application.yaml`):```yaml
spring:
application:
name: zdfmediathek-mcp
ai:
mcp:
server:
enabled: true
name: zdf-mediathek-mcp
protocol: streamable
streamable-http:
mcp-endpoint: /
security:
oauth2:
client:
registration:
zdf:
client-id: ${ZDF_CLIENT_ID}
client-secret: ${ZDF_CLIENT_SECRET}
client-authentication-method: client_secret_post
authorization-grant-type: client_credentials
provider:
zdf:
token-uri: https://prod-api.zdf.de/oauth/token
# Server Configuration
server:
port: ${SERVER_PORT:8080}
# ZDF API Configuration
zdf:
url: https://prod-api.zdf.de
client.id: ${ZDF_CLIENT_ID}
client.secret: ${ZDF_CLIENT_SECRET}
# Logging
logging:
level:
eu.wiegandt.zdfmediathekmcp: ${LOG_LEVEL:INFO}
OAuth2设置:
- 注册ZDF API访问:https://developer.zdf.de/limited-access
- 获取客户端凭据(客户端ID和密码)
- 设置环境变量或通过Docker传递
API覆盖范围
此MCP服务器提供对以下ZDF API功能的访问:
- 内容搜索:ZDF Mediathek内容全文搜索
- 项目时间表:所有ZDF频道(ZDF、ZDFneo、ZDFinfo、3sat等)的电视节目表
- 实时信息:目前正在播放的节目
- 内容元数据:有关节目、剧集、品牌的详细信息
- 可用性:内容可用性窗口和地理限制
有关API端点文档的详细信息,请参阅: .github/plans/
已知限制
- 内容必须在Mediathek中可用(并非所有播放的内容都可用)
- 地理限制可能适用(API中的地理位置字段)
- API配额限制适用(请查看您的ZDF API协议)
- OAuth2令牌到期需要续订
例子
查询示例
问你的AI助手一些问题,比如:
- “在ZDF Mediathek中搜索Tatort剧集”
- “今晚ZDF有什么节目?”
- “给我看今天ZDFneo的电视节目表”
- “ZDF上有关于气候变化的纪录片吗?”
- “3sat上目前正在播放什么?”
预期的工具调用序列
用户问:“今晚ZDF有什么节目?”
- AI呼叫
get_broadcast_schedule频道=“ZDF”和今天的日期 - AI以可读的格式呈现时间表
用户问:“查找犯罪节目”
- AI呼叫
search_content查询=“犯罪”或“克里米” - AI显示带有标题和描述的搜索结果
贡献
我们欢迎捐款!请确保:
- 遵循Kotlin编码标准和惯例
- 为所有新功能编写测试(TDD方法)
- 针对任何API更改更新文档
- 跑
./gradlew build在提交PR之前成功 - 代码中没有SonarQube问题
有关详细的贡献指南,请参阅 代理商.md.
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
链接
- 模型上下文协议
- 春季AI
- ZDF 媒体
- Kotlin
- 项目计划
