German Newsfeed MCP Server

German Newsfeed MCP Server

免責事項： これは個人による非公式プロジェクトです。ARD の製品ではなく、ARD、 ARD-aktuell、NDR によって運営または推奨されているものでもありません。作者の 職業上の雇用とは独立して開発されています。「ARD」と「tagesschau」はそれぞれの 所有者の商標であり、ここではアクセスする API を説明する目的でのみ使用しています。

このプロジェクトは、公開 API を MCP 対応の AI アシスタントに接続するだけです。API 自体、その運用およびコンテンツについては ARD-aktuell が責任を負っており、本プロジェクトではそれらに関する情報を提供できません。 特に権利者の方から本プロジェクトについて懸念がある場合は、 GitHub issueとしてお知らせください。 十分な根拠のある懸念には速やかに対応します。

30 秒でわかる概要

この Model Context Protocol（MCP）サーバーは、 AI アシスタント（Claude Desktop など）を tagesschau.de の公開ニュース API に接続します。 最新の見出し、カテゴリ別および地域別のニュース、全文検索を、API キー不要でローカルの stdio 経由で利用できます。

例：「Was sind die aktuellen Schlagzeilen?」と尋ねると、アシスタントは 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 は次のような質問に回答できます。

• 「Was sind die aktuellen Schlagzeilen?」
• 「Zeig mir die neuesten Wirtschaftsnachrichten.」
• 「Suche nach Artikeln über Ukraine.」
• 「Welche Regionalnachrichten gibt es aus Bayern?」

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 の 運営者でもコンテンツの権利者でもありません。このプロジェクトでは 同ドキュメントを参考にしましたが、利用権を付与するものではありません。

適用される制限：1 時間あたり最大 60 リクエスト。CC ライセンスに基づく 提供を除き、コンテンツを再公開することは禁止されています （https://tagesschau.de/creativecommons）。各インスタンスの運営者が 遵守の責任を負います。

tagesschau.de の robots.txt では、さらにドイツ著作権法第 44b 条第 3 項に基づく 明示的な権利留保が宣言されています（2026-05-19 時点）：書面による 同意なく、テキストおよびデータマイニングを行うこと、ならびに AI モデルの トレーニングやファインチューニングのためにコンテンツを自動利用することは 禁止されています。検索拡張生成（RAG）またはグラウンディングのみを目的とする 自動アクセスは、robots.txt の技術的な指示に従い、コンテンツの出典を 明示することを条件に、明示的に除外されています。このサーバーはその 例外に該当します。コンテンツは出典リンクとともにのみアシスタントへ渡されます。 取得したコンテンツを AI モデルのトレーニングに使用してはなりません。

---

機能

🗞️ ライブニュース	最新ニュース、カテゴリ別ニュース、地域ニュースをリアルタイムで取得します
🔍 全文検索	利用可能なすべての記事を検索します
📺 ライブストリーム	利用可能なチャンネルと HLS ストリーム URL をすべて一覧表示します
⏱️ レート制限	API の 1 時間あたり 60 リクエストの上限を守るローカルトークンバケット
🚀 デュアルトランスポート	ローカルの Claude Desktop には stdio、リモート／Docker には streamable-http を使用します
🐳 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 の設定ファイルを開きます：

OS	パス
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"
      ]
    },

Step 4: Claude Desktop を再起動する

アプリケーションを終了して再度開くか、アプリケーションに応じて MCP サーバーを再読み込みします。

Step 5: 試してみましょう！

アシスタントに次のように尋ねます。

"Was sind die aktuellen Nachrichten?"

---

リモート／Docker デプロイ

ご自身またはチーム内で使用するためのセルフホストです。推奨されるデフォルトは stdio です（クイックスタート（ローカルの Claude Desktop）を参照）。streamable-http トランスポートは、意図的に選択するオプションです。

セキュリティに関する注意： HTTP トランスポートには認証機能がありません。前段に認証レイヤー（リバースプロキシなど）を設けずに、インスタンスをパブリックに公開しないでください。そのため、Compose の設定ではポートを 127.0.0.1 のみにバインドしています。インスタンスを第三者からアクセス可能にした場合は、利用規約に基づく責任ある運用者となります。

レートリミッターの制限： stateless_http=True が指すのは MCP セッションであり、レートリミッターではありません。トークンバケットは、プロセス内のメモリー上に保持される状態です。これにより、次の 2 つの制限があります。

1. 同じ上流 API に対して複数のレプリカを稼働させると、リクエスト予算がその数だけ増えます。
2. コンテナーを再起動すると、バケットは満杯の状態にリセットされます。restart: unless-stopped とクラッシュループが組み合わさると、上限を超える可能性があります。ログを確認してください。

（従来の sse トランスポートも引き続きサポートされています。）

前提条件

• Docker 24+
• Docker Compose v2+

Step 1: .env ファイルを作成する

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

Step 2: ビルドして起動する

docker compose up --build -d

または：

make docker-build
make docker-run

サーバーは http://localhost:8000 で起動します。

Step 3: ヘルスチェックを確認する

docker compose logs german-newsfeed-mcp
docker compose ps

または：

make docker-logs

Step 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 に対する、1 時間あたりのローカルリクエスト予算
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

トップニュースを取得します。

各項目の全文を返します（ホームページのフィード）。また、各項目には get_article が受け付ける 🔗 Volltext: リンクが付属します。

パラメーター	型	デフォルト	説明
limit	int	10	返す項目の最大数

---

get_article

1 件の記事の全文を取得します。

get_latest_news、get_news_by_ressort、get_regional_news の各項目に表示される 🔗 Volltext: リンクを指定します。通常の https://www.tagesschau.de/<path>.html 形式の記事リンクも使用できます。

Parameter	Type	Default	Description
url	str	—	ニュース一覧に表示される記事リンク

呼び出し 1 回につき、60 回／時の上限から上流へのリクエストをちょうど 1 回消費します。すべての見出しではなく、重要な記事に対して呼び出してください。

search_news の結果には記事リンクが含まれないため、get_article に渡すことはできません。まず get_latest_news、get_news_by_ressort、または get_regional_news で記事を探してください。

---

get_news_by_ressort

カテゴリでニュースを絞り込みます。

メタデータ（タイトル、トップライン、日付、ティーザー文）のみを返し、記事の全文は返しません。各項目には 🔗 Volltext: リンクが含まれ、get_article で全文を取得できます。

Parameter	Type	Default	Description
ressort	str	—	inland ausland wirtschaft sport video investigativ wissen
limit	int	10	返す最大項目数

Ressort 文字列は自動的に小文字に正規化されます。"Inland"、"INLAND"、"inland" はすべて同じものとして扱われます。

---

get_regional_news

ドイツの特定の州のニュースを取得します。

メタデータ（タイトル、トップライン、日付、ティーザー文）のみを返し、記事の全文は返しません。各項目には 🔗 Volltext: リンクが含まれ、get_article で全文を取得できます。地域ニュースは ARD の州放送局から提供されるため、放送局名を記載した 📰 Quelle: 行も含まれます。

Parameter	Type	Default	Description
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 に渡すことはできません。

Parameter	Type	Default	Description
search_text	str	—	検索クエリ
page_size	int	10	1 ページあたりの結果数（最大 30 件）
result_page	int	0	ページオフセット（0 始まり）

---

get_channels

ストリーム URL を含む、すべてのライブチャンネルを一覧表示します。

(パラメーターなし)

---

利用可能なリソース

リソースは、MCP クライアントが直接読み取れる URI です。

URI	Description
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）

各モジュールは、それぞれ1つの責務のみを担います：

モジュール	責務
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件）を使い切っています。上流にはリクエストが送信されていません。時間をおいて再試行してください。

テストでのインポートエラー

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 という1か所で定義されています。API の変更はここで追跡できます。

CI ジョブ upstream-check（.github/workflows/ci.yml）は毎週、実際の API に対してこれらのライブテストを実行し、レスポンス形式が一致しなくなった場合は明確に失敗します。

---

ライセンスと謝辞

Apache License 2.0。

提供されるニュース記事のコンテンツは ARD 放送局のものであり、その権利および tagesschau.de の利用規約が適用されます。詳しくはデータソースと利用規約をご覧ください。

API の文書化に協力してくださった**AndreasFischer1985**、bund.dev コミュニティ、そして何より、このプロジェクトが伝えるニュースを制作している ARD 放送局のジャーナリストの皆さんに感謝します。