ZDF 媒体库 MCP 服务器

![License: MIT](https://opensource.org/licenses/MIT) ![Kotlin](http://kotlinlang.org) ![Status](<>) ![MCP](<>) ![Quality Gate Status](https://sonarcloud.io/summary/new_code?id=Nicklas2751_zdfmediathek-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）

工具使用示例

搜索内容：

{
  "tool": "search_content",
  "arguments": {
    "query": "Tatort",
    "limit": 5
  }
}

获取广播时间表：

{
  "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
  }
}

获取当前广播：

{
  "tool": "get_current_broadcast",
  "arguments": {
    "tvService": "ZDFneo",
    "limit": 10
  }
}

使用AI客户端

先决条件

ZDF API证书：获取OAuth2凭据

从 ZDF开发者门户

码头工人：在您的系统上安装Docker

MCP传输类型

此服务器支持 两种运输方式 （一次只有一个活动）：

1.流式HTTP传输（默认）

最适合：生产、远程访问、多个客户端

默认情况下处于活动状态。 服务器在正常启动时使用HTTP传输运行。

端点： http://localhost:8080/

Docker：

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客户端配置：

{
  "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)

配置：

{
  "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

配置示例：

{
  "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"
      }
    }
  }
}

用途：

将配置添加到您的 claude_desktop_config.json
重新启动克劳德桌面
Claude将在需要时自动启动Docker容器（stdio传输）
问克劳德：“在ZDF媒体中心寻找泰特”

GitHub Copilot命令行界面

运输： Stdio（由Copilot CLI管理的Docker）

先决条件：

# Install GitHub Copilot CLI (if not already installed)
gh extension install github/gh-copilot

设置：

在中配置MCP服务器 ~/.config/github-copilot/mcp-servers.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"
      }
    }
  }
}

用途：

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）：

{
  "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"
      }
    }
  }
}

用途：

在VS Code中打开Copilot聊天
选择“代理”模式
单击工具图标查看可用的MCP服务器
问：“在ZDF Mediathek中搜索Tatort”

IntelliJ IDEA与GitHub Copilot

运输： Stdio（由IntelliJ管理的Docker）

插件要求：

GitHub复制插件
IntelliJ IDEA 2024.3或更高版本

配置：

在IntelliJ IDEA中，打开GitHub Copilot聊天窗口
点击 “+添加更多工具” 在聊天窗口的底部
这将打开 mcp.json 配置文件（通常位于 ~/.config/github-copilot/intellij/mcp.json)
添加ZDF Mediathek MCP服务器配置：

{
  "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”
添加配置：

{
  "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 在您的项目根目录中。

用途：

在Kilo Code聊天界面中键入您的请求
Kilo Code将自动检测并使用ZDF Mediathek MCP工具
问：“ZDF目前有什么？”

其他MCP客户端

对于任何兼容MCP的客户端：

选项1:标准传输（通过Docker）

{
  "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传输

启动服务器：

   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

配置您的客户端：

   {
     "mcpServers": {
       "zdfmediathek-mcp": {
         "type": "streamable-http",
         "url": "http://localhost:8080"
       }
     }
   }

开发设置

先决条件

JDK 21或更高版本
Gradle 8+（包括包装）
Docker（用于容器化部署）

从源代码构建

# 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):

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端点文档的详细信息，请参阅：

已知限制

内容必须在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许可证获得许可-请参阅许可证文件以获取详细信息。

Zdfmediathek MCP

快速接入

详细介绍

ZDF 媒体库 MCP 服务器

概述

主要特点

MCP工具参考

工具使用示例

使用AI客户端

先决条件

MCP传输类型

1.流式HTTP传输（默认）

2.标准运输

拟人克劳德桌面

GitHub Copilot命令行界面

VS代码与GitHub Copilot

IntelliJ IDEA与GitHub Copilot

基洛代码

其他MCP客户端

开发设置

先决条件

从源代码构建

配置

API覆盖范围

已知限制

例子

查询示例

预期的工具调用序列

贡献

许可证

链接

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP