German Newsfeed MCP Server

German Newsfeed MCP Server

免责声明： 这是一个私人、非官方项目。它不是 ARD 产品，也不由 ARD、 ARD-aktuell 或 NDR 运营或认可。该项目独立于作者的职业工作开发。 “ARD”和“tagesschau”是各自所有者的商标，此处仅用于说明所访问的 API。

本项目仅将公共 API 接入支持 MCP 的 AI 助手。ARD-aktuell 负责 API 本身、 API 的运行及其内容；本项目无法提供与上述任何事项有关的信息。如对本项目有任何疑虑， 尤其是权利持有者的疑虑，请通过 GitHub issue 提出。经核实的疑虑将得到及时处理。

三十秒了解

这个 Model Context Protocol (MCP) 服务 可将你的 AI 助手（Claude Desktop 等）连接到 tagesschau.de 的公共新闻 API：最新头条、分类和地区新闻，以及全文搜索。通过本地 stdio 连接， 无需 API 密钥。

例如，当用户询问 “当前有哪些头条新闻？” 时，助手会回答 tagesschau.de 当前的热门新闻，并提供每条新闻的标题、日期、摘要和文章链接。

语言：

• 🇩🇪 德语
• 🇬🇧 英语

---

目录

1. 这是什么？
2. 数据来源和使用条款
3. 功能
4. 项目结构
5. 本地快速开始（Claude Desktop）
6. 远程 / Docker 部署
7. 配置参考
8. 可用工具
9. 可用资源
10. 开发指南
11. 运行测试
12. Makefile 参考
13. 故障排除
14. 停止工作时
15. 许可证和致谢

---

这是什么？

这个 MCP 服务会将 tagesschau.de 的公共新闻 API 接入你的 AI 助手（Claude、Open Claw 等）。

连接后，你的 AI 可以回答如下问题：

• “当前有哪些头条新闻？”
• “给我看看最新的经济新闻。”
• “搜索有关乌克兰的文章。”
• “巴伐利亚有哪些地区新闻？”

有关 API 及其使用条款的详情，请参阅数据来源和使用条款。无需 API 密钥。

---

数据源和使用条款

此服务会调用由 ARD-aktuell 运营的公开端点 www.tagesschau.de/api2u/。所提供的 内容源自 ARD 各广播机构，仍受其权利以及 tagesschau.de 的使用条款约束： https://www.tagesschau.de/nutzungsbedingungen/

该 API 没有官方文档。bund.dev 提供了社区文档 （https://tagesschau.api.bund.dev）。bund.dev 是一个公民社会文档项目， 既不是 API 的运营方，也不是内容的权利持有者。该项目将其文档用作 参考，但这并不授予任何使用权。

适用限制：每小时最多 60 次请求；除以 CC 许可提供的内容外， 不得重新发布内容 （https://tagesschau.de/creativecommons）。遵守这些要求的 责任由运营相应实例的一方承担。

tagesschau.de 的 robots.txt 还明确声明，根据《德国著作权法》第 44b(3) 条 （截至 2026-05-19）保留权利：未经书面同意，禁止进行文本与数据挖掘， 也禁止将内容自动用于 AI 模型的训练或微调。明确豁免的是仅为检索增强生成（RAG） 或提供依据而进行的自动访问，前提是遵守 robots.txt 的技术指令， 并且内容仍标注其原始来源。此服务属于该豁免范围：它仅在附带来源链接的 情况下将内容传递给助手。检索到的内容不得用于训练 AI 模型。

---

功能

🗞️ 实时新闻	实时获取突发新闻、分类新闻和地区新闻
🔍 全文搜索	搜索所有可用文章
📺 直播流	列出所有可用频道和 HLS 流 URL
⏱️ 速率限制器	使用本地令牌桶遵守 API 每小时 60 次的限制
🚀 双传输模式	stdio 用于本地 Claude Desktop；streamable-http 用于远程 / Docker
🐳 支持 Docker	多阶段镜像、非 root 用户、健康检查、资源限制
✅ 273 项测试	251 项单元测试 + 22 项实时集成测试
🛠️ Makefile	make test、make lint、make docker-build 等
🔒 无需密钥	公共 API，无需 API 密钥

---

项目结构

german-newsfeed-mcp/
├── src/
│   └── german_newsfeed_mcp/
│       ├── __init__.py      # Package metadata
│       ├── config.py        # Environment-driven configuration
│       ├── client.py        # Async HTTP client (httpx) + error handling
│       ├── rate_limiter.py  # Token-bucket rate limiter
│       ├── validators.py    # Domain constants + validation helpers
│       ├── formatters.py    # Markdown rendering of news items & channels
│       ├── tools.py         # MCP tool business logic
│       ├── resources.py     # MCP resource business logic
│       └── server.py        # Composition root: FastMCP + run() entry-point
├── tests/
│   ├── conftest.py          # Shared fixtures & mock payloads
│   ├── test_client.py       # Client unit + live integration tests
│   ├── test_rate_limiter.py # Rate-limiter unit tests
│   ├── test_validators.py   # Validator unit tests (URL & ressort checks)
│   ├── test_formatters.py   # Formatter unit tests (pure functions)
│   ├── test_tools.py        # Tool unit + live integration tests
│   └── test_resources.py    # Resource unit + live integration tests
├── main.py                  # Thin entry-point (calls server.run())
├── pyproject.toml           # Project metadata, deps, pytest & pylint config
├── uv.lock                  # Locked dependency graph (commit this!)
├── Dockerfile               # Multi-stage production image
├── docker-compose.yml       # One-command remote deployment
├── .env.example             # Configuration template
├── Makefile                 # Developer shortcuts (test, lint, docker, clean)
├── CHANGELOG.md             # Version history
├── CONTRIBUTING.md          # How to contribute
└── README_de.md             # German version of this file

---

本地快速开始（Claude Desktop）

也适用于其他 AI 助手，请改为编辑相应的配置文件。此模式使用 stdio 传输；服务将作为子进程启动。无需端口。

前置条件

• macOS / Linux / Windows (WSL2)
• Python 3.12+
• uv：curl -LsSf https://astral.sh/uv/install.sh | sh
• Claude Desktop

步骤 1：克隆并安装

git clone https://github.com/Jakolo121/german-newsfeed-mcp.git
cd german-newsfeed-mcp
uv sync

步骤 2：验证是否正常运行

uv run python -c "from german_newsfeed_mcp.server import mcp; print('OK!', mcp.name)"
# Expected: OK! German Newsfeed MCP

步骤 3：连接 Claude Desktop

打开 Claude Desktop 配置文件：

操作系统	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

添加以下条目（根据克隆目录调整路径）：

    "german-newsfeed": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/german-newsfeed-mcp",
        "run",
        "german-newsfeed-mcp"
      ]
    },

步骤 4：重启 Claude Desktop

退出并重新打开应用，或根据应用的情况重新加载其 MCP 服务。

步骤 5：试试看！

向你的助手提问：

"当前的新闻有哪些？"

---

远程 / Docker 部署

用于个人或团队内部的可自托管部署。推荐的默认方式是 stdio（请参阅快速开始（本地 Claude Desktop））；streamable-http 传输方式需要你有意选择。

安全提示： HTTP 传输没有身份验证。请勿在前面没有身份验证层（例如反向代理）的情况下将其公开。为此，Compose 设置有意仅将端口绑定到 127.0.0.1。任何让实例可供第三方访问的人，都将根据使用条款成为责任运营者。

速率限制器的局限： stateless_http=True 指的是 MCP 会话，而不是速率限制器。令牌桶是进程本地的内存状态。因此有以下两个局限：

1. 多个副本访问同一上游 API 时，请求额度会相应倍增。
2. 容器重启会将令牌桶重置为满额。若同时配置了 restart: unless-stopped 且发生崩溃循环，就可能超出限制。请留意日志。

（仍支持旧版 sse 传输方式。）

前提条件

• Docker 24+
• Docker Compose v2+

步骤 1：创建你的 .env 文件

cp .env.example .env
# Edit .env if you want a different port or log level

步骤 2：构建并启动

docker compose up --build -d

或者：

make docker-build
make docker-run

服务会在 http://localhost:8000 启动。

步骤 3：检查运行状况

docker compose logs german-newsfeed-mcp
docker compose ps

或者：

make docker-logs

步骤 4：连接 Claude Desktop（Streamable HTTP）

    "german-newsfeed": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    },

对于外部服务：请先在前面添加身份验证层（参见上方的安全提示），然后调整 docker-compose.yml 中的回环绑定，并将 localhost 替换为代理的地址。

停止 / 更新

docker compose down
docker compose up --build -d

---

配置参考

所有设置均从环境变量（或 .env 文件）读取。

变量	默认值	说明
TRANSPORT	stdio	stdio 或 streamable-http（旧版 sse）
HOST	0.0.0.0	绑定地址（仅限 HTTP 传输方式）
PORT	4200	HTTP 端口（仅限 HTTP 传输方式）
LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR
RATE_LIMIT_PER_HOUR	60	每小时向上游 API 发起请求的本地额度
USER_AGENT_CONTACT	—	可选：User-Agent 标头中的联系信息；未设置时省略

直接运行时（uv run german-newsfeed-mcp）会使用默认值。 Compose 设置会覆盖这些值：将 HOST 设为 0.0.0.0，并将 PORT 设为 8000 （请参阅 docker-compose.yml）。

---

可用工具

你的 AI 助手可以调用以下工具。

get_latest_news

获取头条新闻。

返回每条新闻的完整文章文本（主页信息流）。每条新闻还包含一个 🔗 Volltext: 链接，可供 get_article 使用。

参数	类型	默认值	说明
limit	int	10	返回的最大条目数

---

get_article

获取单篇文章的完整文本。

接受 get_latest_news、get_news_by_ressort 和 get_regional_news 返回的每条新闻中附带的 🔗 Volltext: 链接；也可以使用普通的 https://www.tagesschau.de/<path>.html 文章链接。

参数	类型	默认值	描述
url	str	—	新闻列表中显示的文章链接

每次调用恰好消耗每小时 60 次上游请求额度中的 1 次——只对重要文章调用，不要为列表中的每条标题都调用。

search_news 的结果不带文章链接，因此不能传递给 get_article。请先通过 get_latest_news、get_news_by_ressort 或 get_regional_news 查找文章。

---

get_news_by_ressort

按类别筛选新闻。

仅返回元数据——标题、导语、日期和一句摘要，不包含完整文章文本。每条新闻都附带一个 🔗 Volltext: 链接，可通过 get_article 获取完整文本。

参数	类型	默认值	描述
ressort	str	—	inland ausland wirtschaft sport video investigativ wissen
limit	int	10	返回的最大条目数

Ressort 字符串会自动转换为小写："Inland"、"INLAND" 和 "inland" 都等效。

---

get_regional_news

获取德国特定州的新闻。

仅返回元数据——标题、导语、日期和一句摘要，不包含完整文章文本。每条新闻都附带一个 🔗 Volltext: 链接，可通过 get_article 获取完整文本；由于地区新闻来自 ARD 州级广播机构，因此还会附带一行 📰 Quelle:，注明该广播机构的名称。

参数	类型	默认值	描述
region_id	int	—	1=BW · 2=BY · 3=BE · 4=BB · 5=HB · 6=HH · 7=HE · 8=MV · 9=NI · 10=NW · 11=RP · 12=SL · 13=SN · 14=ST · 15=SH · 16=TH
ressort	str	None	可选的类别筛选条件
limit	int	10	返回的最大条目数

---

search_news

在所有可用文章中进行全文搜索。

仅返回元数据——标题、日期和文章类型，不包含完整文章文本。搜索结果不带文章链接，因此不能传递给 get_article。

参数	类型	默认值	描述
search_text	str	—	搜索查询
page_size	int	10	每页结果数（最多 30 条）
result_page	int	0	页偏移量（从 0 开始）

---

get_channels

列出所有带流媒体 URL 的直播频道。

(无参数)

---

可用资源

资源是可寻址的 URI，MCP 客户端可以直接读取。

URI	描述
news://tagesschau/homepage	首页头条新闻
news://tagesschau/news/{ressort}	按类别筛选的新闻
news://tagesschau/regional/{region_id}	按州 ID 筛选的地区新闻
news://tagesschau/search/{search_text}	搜索结果
news://tagesschau/channels	可用频道和流媒体

---

开发指南

设置

git clone https://github.com/Jakolo121/german-newsfeed-mcp.git
cd german-newsfeed-mcp
uv sync --extra dev

启动服务：

uv run german-newsfeed-mcp

或者：

make run

代码组织（SOLID）

每个模块都只负责一项职责：

模块	职责
config.py	读取并公开环境变量
client.py	HTTP 请求和错误处理
rate_limiter.py	本地请求额度（令牌桶）
validators.py	领域常量（VALID_RESSORTS）和输入验证
formatters.py	将原始 API 字典转换为 Markdown
tools.py	验证输入、调用客户端、调用格式化器
resources.py	与工具相同，但用于 MCP 资源
server.py	组合根：组装 FastMCP、注册处理程序并启动

添加新工具

1. 在 tools.py 中添加一个 tool_<name>() 异步函数
2. 在 server.py 中使用 @mcp.tool() 注册
3. 在 tests/test_tools.py 中编写单元测试和集成测试

---

运行测试

单元测试（无需联网，速度快）

uv run pytest -m "not integration"     # run all unit tests
uv run pytest -m "not integration" -v  # verbose output
uv run pytest tests/test_formatters.py # single file

或者：

make test

实时集成测试（需要联网）

uv run pytest -m integration           # all live tests
uv run pytest -m integration -v        # verbose

完整测试套件

uv run pytest

或者：

make test-all

质量门禁（代码检查和测试）

uv run pylint src/german_newsfeed_mcp/
uv run pytest

或者：

make check

预期结果

251 passed            ← unit tests (no network)
 22 selected          ← integration tests (live API)

---

Makefile 参考

make test          # fast unit tests (no network, ~0.3 s)
make test-all      # unit + live integration tests
make lint          # pylint
make check         # lint + unit tests — use as CI gate
make run           # start server in stdio mode (Claude Desktop)
make run-http      # start server in streamable-http mode
make docker-build  # build Docker image
make docker-run    # docker compose up -d
make docker-stop   # docker compose down
make docker-logs   # tail docker compose logs
make clean         # remove __pycache__, .pytest_cache, dist, etc.

---

故障排除

Claude Desktop 未显示 MCP 工具

1. 检查 claude_desktop_config.json 路径是否为绝对路径
2. 在终端中运行 uv run python main.py，程序应能无错误启动
3. 完全退出并重新打开 Claude Desktop（按 Cmd+Q，而不只是关闭窗口）

Docker 容器立即退出

docker compose logs german-newsfeed-mcp

或者：

make docker-logs

常见原因：TRANSPORT 值错误（在 Docker 中必须为 streamable-http），或端口已被占用。

API 超时

上游 API 偶尔会对某些端点进行速率限制。这是正常现象，服务会返回描述性错误消息，而不会崩溃。请几秒后重试。

速率限制错误

如果服务报告“Rate limit exceeded”，则本地请求额度（RATE_LIMIT_PER_HOUR，默认值为 60/h）已用尽。请求尚未发送至上游。请稍后重试。

测试中的导入错误

uv sync --extra dev     # ensure dev deps are installed
uv run pytest           # always run via uv, not bare pytest

---

停止工作时

上游 API 没有官方文档，可能会在不另行通知的情况下发生变化。如果工具突然返回空列表或错误消息，而 tagesschau.de 仍可访问，并且实时集成测试失败（uv run pytest tests/ -m integration），就说明 API 可能已发生变化。

所有端点都定义在同一处：src/german_newsfeed_mcp/client.py 中的 ENDPOINTS。可以在此处追踪 API 变更。

CI 作业 upstream-check（.github/workflows/ci.yml）每周都会针对真实 API 运行这些实时测试；当响应格式不再匹配时，它会明确报错。

---

许可证与致谢

Apache License 2.0。

提供的新闻内容归 ARD 广播机构所有，并受其相关权利及 tagesschau.de 使用条款约束，详见数据来源和使用条款。

感谢 AndreasFischer1985、记录该 API 的 bund.dev 社区，尤其感谢 ARD 广播机构的记者们。本项目只是传递他们的作品。