gdelt-mcp-server

---

概要

GDELT Project によるニュースとテレビ報道の分析：65 以上の言語による過去 3 か月分の世界のニュースと、2009 年から 2024 年 10 月までの 150 以上の局の米国テレビ番組のトランスクリプトを利用できます。記事やクリップを検索し、報道の急増を追跡し、論調を分析して、あるニュースが言語や国を越えてどのように広がったかをたどれます。

ツール

ツール	説明
gdelt_search_articles	全文検索とフィルター演算子を使って、過去3か月間の世界のニュース報道（65以上の言語）を検索します。最大250件の記事を取得し、48,000バイトの応答に収まる件数を返します。残りを再検索するための日付範囲も返します。
gdelt_get_coverage_timeline	クエリに対する報道量または平均トーンの時系列を取得します。volume_with_articles モードでは、急増した時点ごとの主要記事も含まれます。points を指定すると、名前付きの時点における記事リスト全体を取得できます。48,000バイトの応答内で offset を使ってページ分割します。
gdelt_get_tone_distribution	報道が一様に否定的か、二峰性か、中立付近に集中しているかを示すトーンのヒストグラム（約−30～+30のビン）を取得します。48,000バイトの応答内で offset を使ってページ分割します。
gdelt_get_coverage_breakdown	報道量を発信元の言語または国別に分類します。地理的な広がりを示す複数系列の時系列です。値は記事数ではなく、メディア報道に占める割合を正規化したものです。48,000バイトの応答内で offset を使ってページ分割します。
gdelt_search_themes	DOC ツールが受け付ける theme: 演算子用の GKG テーマ識別子を検索します。drought からは NATURAL_DISASTER_DROUGHT、cyberattack からは CYBER_ATTACK が見つかります。GDELT のテーマ検索リストにある件数順に表示します。
gdelt_search_tv	米国のテレビニュースのクローズドキャプション（2009年～2024年10月）を検索し、放送局ごとの放送時間の時系列を返します。
gdelt_get_tv_clips	該当するテレビクリップを、文字起こしの抜粋と Internet Archive の視聴リンクとともに取得します。最大3,000件を取得し、48,000バイトの応答に収まる件数を返します。残りを再検索するための日付範囲も返します。
gdelt_get_tv_context	クエリに一致するテレビクリップのうち、GDELT の関連度順サンプルに含まれるクリップから、同時に頻出する単語やフレーズを取得します。
gdelt_list_tv_stations	市場、ネットワーク、監視期間とともにテレビ局を一覧表示します。すべてのテレビ局、または局 ID、ネットワーク、市場で絞り込んだテレビ局を表示し、検索前に利用可能な局を確認できます。

機能リファレンス

gdelt_search_articles _ツール

• GDELT の完全なクエリ構文に対応しています。フレーズ、ブール演算子 OR、除外、フィルター演算子（sourcecountry:、sourcelang:、domain:、theme:、tone<／tone>）、近接検索（near20:）、繰り返し検索（repeat3:）を使用できます。theme: で使用する識別子は gdelt_search_themes で検索できます
• 並べ替え方法（relevance、dateDesc、dateAsc、toneDesc、toneAsc、hybridRel）と取得件数を設定できます。1回の呼び出しで最大250件です。maxRecords を2,500まで指定すると、250件ずつ実行され、上限が適用されたことが limitClamp に報告されます。2,500を超える指定は拒否されます
• URL、タイトル、公開日、ドメイン、言語、発信元の国、ソーシャル画像の URL を返します
• 応答には48,000バイトの上限内に収まる記事が含まれます。残りの件数は withheldCount に記録され、再検索する日付範囲は continuationWindows に示されます（url で重複を除去してください）。250件は固定の上限であり、ページサイズではありません。そのため、この上限を超えて取得するには日付範囲を絞り込む必要があります
• 明示的な startDatetime／endDatetime の範囲外にある記事は除外され、その件数は通知に記載されます

---

gdelt_get_coverage_timeline _ツール

• 3 つのモードがあります：volume（各タイムステップで正規化した割合）、volume_with_articles（急増ごとの上位記事をボリュームに追加 — 1 回の呼び出しでシグナルを検出）、tone（各タイムステップの平均センチメント）
• 各タイムステップには、真の件数である referenceCount の横に最初の 3 件の記事リンクが含まれます。points: ["<date>"] を指定すると、指定したタイムステップのみが返され、それぞれすべてのリンクが含まれます
• レスポンスには、48,000 バイトの上限に収まる範囲で、できるだけ多くのタイムステップ全体が含まれます。途中で切られたページには nextOffset が返されるので、offset として渡してください。各シリーズの pointCount と peak は、すべてのページでシリーズ全体を対象とします
• 平滑化（0～5 タイムステップ）と時間範囲（timespan、または明示的な startDatetime／endDatetime）を設定できます。日付の解像度（15min／hour／day）は、返される間隔から推定されます
• どのタイムステップにも一致しない points の日付、または最後のタイムステップを超える offset は、有効な値とともに拒否されます

---

gdelt_get_tone_distribution _ツール

• 約 −30 から +30 までのヒストグラムのビンです。各ビンには、referenceCount の横に最初の 3 件の記事リンクが含まれます。bins: [<bin>] を指定すると、指定したビンのみが返され、それぞれすべてのリンクが含まれます。どのビンにも一致しない bins の値は、利用可能なビンとともに拒否されます
• ヒストグラム全体を対象とするサマリーフィールド：peakNegativeBin、peakPositiveBin、neutralPct（−2～+2 の範囲にある記事の割合）
• レスポンスには、48,000 バイトの上限に収まる範囲で、できるだけ多くのビン全体が含まれます。途中で切られたページには nextOffset が返されるので、offset として渡してください。gdelt_get_coverage_timeline の tone モードのようなトーンの時系列ではなく、一致するすべての記事を対象とするスナップショットです

---

gdelt_get_coverage_breakdown _ツール

• language または country ごとに、複数シリーズの時系列に分類します。合計値が上位 10 件のシリーズが含まれ、その他のシリーズは otherSeriesLabels に名前が記載されます
• series: ["<label>"] を指定すると、指定したシリーズのみが完全な状態で selectedSeries に返されます。どのシリーズにも一致しないラベルは、利用可能なラベルとともに拒否されます
• レスポンスには、48,000 バイトの上限に収まる範囲で、できるだけ多くのシリーズ全体が含まれます。途中で切られたページには nextOffset が返されるので、offset として渡してください
• 値は各ソースのメディア出力に占める正規化された割合であり、記事数ではありません。そのため、ソース間で合計しないでください

---

gdelt_search_themes _ツール

• GDELT の GKG テーマ参照表（59,315 件のテーマ）の識別子を検索します。一致した各項目には、識別子、記載件数、および theme:TAX_DISEASE_OUTBREAK のような貼り付けてすぐに使える operator が含まれます
• 大文字と小文字は区別されません。語形変化や同義語は考慮されず、識別子の一部に一致する語が検索されます（cyberattack → CYBER_ATTACK、plant disease → TAX_PLANTDISEASE）。一致するものがない場合は、末尾の s を削除して 1 回再試行し、その旨が通知されます（protests → PROTEST）
• 完全一致、記載件数（リアルタイムの記事総数ではなく、固定の普及度の数値）、識別子の順にランク付けされます
• offset／limit でページ分割します（1～100、デフォルトは 25。limit が 1,000 以下の場合は 100 件ずつ実行され、上限に調整されたことが limitClamp に報告されます。1,000 を超えると呼び出しは拒否されます）。さらに一致するものがある場合のみ nextOffset が表示されます。結果が空でない状態で範囲を超えるオフセットを指定すると、offset_out_of_range エラーになります
• DOC と TV のレート制限による待機列には入りません

---

gdelt_search_tv _ツール

• 構造化された stations（例：["CNN", "FOXNEWS"]）を最大10件指定するか、クエリに埋め込んだ station: セレクターを指定します。どちらの場合も、TV API では少なくとも1つが必要です
• normalize は、相対放送時間の割合（デフォルト）と、生の一致数である15秒クリップ数を切り替えます。任意の dateres 集計（hour／day／week／month／year）も指定できます。TV の演算子：station:、network:、market:、show:、context:
• 各系列には station（stations 入力で使用する ID。FOXNEWS）と stationName（GDELT のラベル。FOX News）が含まれます。ID を解決できない場合、系列には station を含めず stationName のみが残り、その旨が通知に記載されます
• 1回の呼び出しにつき最大500ポイントを、日付順、次に局名順でページ分割して返します。次のページを取得するには、同じ入力で nextOffset を渡します。limit を最大5,000まで指定すると、500単位で実行され、上限調整が limitClamp に報告されます。5,000を超えると呼び出しは拒否されます。テキスト表示に含まれる局ごとの件数、合計、ピーク値は、返されたページのみを対象とします
• 最近のニュースを照会する前に、gdelt_list_tv_stations で局の日付範囲を確認してください

---

gdelt_get_tv_clips _ツール

• 1回の呼び出しにつき最大3,000件のクリップを取得し、関連度順、日付の降順、または日付の昇順で並べ替えます。maxRecords を最大30,000まで指定すると、3,000単位で実行され、上限調整が limitClamp に報告されます。30,000を超えると呼び出しは拒否されます
• 各クリップには、番組名、station と stationName（gdelt_search_tv と同じ方法で解決されるため、系列の station はそのまま stations に渡せます）、放送日時、15秒の文字起こし抜粋、Archive.org への直接リンク、任意のサムネイルが含まれます
• サーバーは1時間単位で取得するため、期間の幅は任意です。明示的な startDatetime／endDatetime の範囲外にあるクリップは除外され、その件数が通知に記載されます（timespan を指定した呼び出しでは除外されません）
• レスポンスには48,000バイトの上限に収まるだけのクリップが含まれます。残りは withheldCount に件数が記録され、それらを再取得するための期間が continuationWindows に示されます（archiveUrl で重複を除去してください）。3,000はハード上限でありページサイズではないため、この上限を超えて取得するには期間を狭める必要があります

---

gdelt_get_tv_context _ツール

• クエリと共起する、ストップワード以外の語句を出現頻度順に返します
• 語句とスコアは、一致するクリップすべてではなく、関連度の高いクリップ200件の GDELT サンプルから取得されます。空でないレスポンスには、その旨が必ず notice に記載されます。期間や局を比較する場合は、それぞれ別に範囲を絞って呼び出してください
• 相対頻度のスコアは0～100で、クエリ語自体のスコアは100です

---

gdelt_list_tv_stations _ツール

• 市場、ネットワーク、モニタリング開始日、終了日とともに、すべての局を返します。または、任意の stations、network、market フィルターに一致する局のみを返します
• フィルターは大文字と小文字を区別せず、値全体で照合され、AND 条件で組み合わされます（network: "FOX" は FOXNEWS に一致しません）。activeCount と totalCount は、返された局の件数です
• 一致するものがないフィルターまたは局 ID は通知に記載されます。終了日が過去24時間以内の場合、isActive は true です
• 対象期間中に局が放送していたことの確認や、他の TV ツールの stations パラメーターで有効な局 ID を調べるために使用します

特徴

@cyanheads/mcp-ts-core 上に構築されています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースを備えた構造化ログに対応しています。

GDELT 固有の機能：

• DOC ツールと TV ツールで共有するリクエストペーサー：同時実行リクエストは 1 件、5 秒あたり 1 リクエストに制限し、レート制限の応答を受け取るとバックオフ（5 秒から開始し、最大 60 秒まで倍増）します
• TV の生のクエリ構文ではなく、構造化された stations 配列を使用します
• GKG のテーマ検索データは、初回のダウンロード後にメモリ内に保持されます

エージェントに適した出力：

• すべての応答にクエリの内容を含めます。元のクエリと適用された期間が含まれるため、パラメーターを再導出せずに呼び出しを連鎖できます
• 位置ベースの配列ではなく、型付きシリーズの label フィールド（"Volume Intensity"、"Average Tone"、言語名／国名）を使用します
• isActive ブール値と ISO 8601 日付を含む局のメタデータ
• 該当結果がない場合も通常の出力形式を返します。配列は空になり、クエリを広げる方法を notice で案内します

はじめに

公開ホストインスタンス

公開インスタンス https://gdelt.caseyjhand.com/mcp を利用できます。インストールは不要です。Streamable HTTP を使って、任意の MCP クライアントから接続します。

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "streamable-http",
      "url": "https://gdelt.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gdelt-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gdelt-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/gdelt-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーは不要です。GDELT は無料の公開 API です。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/gdelt-mcp-server.git

2. ディレクトリに移動します：

cd gdelt-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if you need to override defaults

設定

すべての設定は、src/config/server-config.ts 内の Zod スキーマを使って起動時に検証されます。主な環境変数：

変数	説明	デフォルト
GDELT_BASE_URL	DOC API と TV API の両方で使用する GDELT API のベース URL を上書きします。	https://api.gdeltproject.org/api/v2
GDELT_REQUEST_DELAY_MS	GDELT リクエスト間の最小間隔をミリ秒で指定します（5 秒あたり 1 リクエストの制限を適用）。	5300
GDELT_REQUEST_TIMEOUT_MS	1 件の GDELT リクエストの制限時間です（リトライを含む呼び出しは、この値の 2 倍以内に制限されます）。	60000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパス。	/mcp
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境用に公開オリジンを上書きします。	none
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。	stateless
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
MCP_GC_PRESSURE_INTERVAL_MS	オプトインで有効にする Bun 専用の強制 GC ループの間隔（ミリ秒）。	0（無効）
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false

オプションで上書きできる項目の一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t gdelt-mcp-server .
docker run --rm -p 3010:3010 gdelt-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/gdelt-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント — ツールを登録し、サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools	ツールの定義（*.tool.ts）。DOC API と TV API、および GKG のテーマ検索に対応する 9 つのツール。
src/services/gdelt	DOC API と TV API をラップする GdeltDocService と GdeltTvService、DOC と TV のすべての呼び出しがキューを通過する共通の送信ペーサー、および GKG のテーマ検索を行う GdeltThemeService。
tests/	src/ に対応するユニットテストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します — ツールのロジックで try/catch は使用しません
• リクエストスコープのログには ctx.log、テナントスコープのストレージには ctx.state を使用します
• src/mcp-server/tools/definitions/index.ts のバレル経由で新しいツールを登録します
• GDELT API の呼び出しは、未加工の JSON を検証 → ドメイン型に正規化 → 出力スキーマを返す、という手順でラップします。不足しているフィールドを捏造してはいけません

コントリビュート

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。