gdelt-mcp-server

---

概述

通过 GDELT Project 分析新闻和电视报道：涵盖最近 3 个月、使用 65 种以上语言的全球新闻，以及 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	查找 GKG 主题标识符，供 DOC 工具接受的 theme: 运算符使用——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:）——gdelt_search_themes 可查找 theme: 接受的标识符
• 可配置排序方式（relevance、dateDesc、dateAsc、toneDesc、toneAsc、hybridRel）和获取数量，每次调用最多 250 篇——maxRecords 设置为不超过 2,500 时，会按每批 250 篇执行，并在 limitClamp 中报告限制；超过 2,500 时会拒绝调用
• 返回 URL、标题、发布日期、域名、语言、来源国家/地区和社交图片 URL
• 响应会尽可能容纳在 48,000 字节预算内的文章；其余文章计入 withheldCount，而 continuationWindows 会提供重新查询这些文章的日期窗口（按 url 去重）。250 篇是硬性上限，而非每页数量，因此只有缩小日期范围才能突破此限制
• 不在明确指定的 startDatetime/endDatetime 窗口内的文章会被剔除，提示信息会统计这些文章的数量

---

gdelt_get_coverage_timeline _工具

• 三种模式：volume（每个时间步的标准化百分比）、volume_with_articles（总量加上每个峰值对应的热门文章——一次调用即可检测信号）、tone（每个时间步的平均情感）
• 每个时间步都会在 referenceCount（实际数量）旁附上前 3 篇文章的链接；points: ["<date>"] 只返回指定的时间步，且每个时间步都附上全部链接
• 响应会在 48,000 字节预算内尽可能包含完整的时间步；截断的页面会返回 nextOffset，供后续作为 offset 传入。每个序列的 pointCount 和 peak 在每一页中都涵盖整个序列
• 可配置平滑范围（0–5 个时间步）和时间范围（timespan，或显式指定 startDatetime/endDatetime）；日期分辨率（15min/hour/day）根据返回的时间间隔推断

---

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 个主题）；每条匹配结果包含标识符、表中列出的数量，以及可直接粘贴使用的 operator，例如 theme:TAX_DISEASE_OUTBREAK
• 不区分大小写，不进行词干提取或同义词扩展：单词会匹配标识符中的部分内容（cyberattack → CYBER_ATTACK，plant disease → TAX_PLANTDISEASE）。如果没有匹配项，会去掉末尾的 s 后重试一次（protests → PROTEST），并在通知中说明
• 排序顺序为：精确匹配优先，其次按表中列出的数量（这是静态普及度数据，并非实时文章总数），最后按标识符排序
• 使用 offset / limit 分页（1–100，默认值为 25；limit 最大可设为 1,000，此时会按 100 运行，并在 limitClamp 中报告截断值；超过 1,000 的调用会被拒绝）；只有仍有更多匹配项时才会出现 nextOffset；对于非空结果，超出范围的 offset 会报错 offset_out_of_range
• 不会排在 DOC 和 TV 速率限制队列之后

---

gdelt_search_tv _工具

• 最多 10 个结构化的 stations（例如 ["CNN", "FOXNEWS"]），或在查询中嵌入 station: 选择器——无论采用哪种方式，TV API 都要求至少提供一个
• normalize 用于切换相对播出时间百分比（默认）与匹配到的原始 15 秒片段数；可选的 dateres 聚合方式为（hour/day/week/month/year）。TV 运算符：station:、network:、market:、show:、context:
• 每个系列都包含 station（stations 输入接受的 ID，例如 FOXNEWS）和 stationName（GDELT 的标签，例如 FOX News）。如果无法解析某个 ID，系列中会保留 stationName，但不包含 station，并会在通知中说明
• 每次调用最多返回 500 个数据点，按日期再按站点名称排序；传入相同的输入并提供 nextOffset 即可获取下一页。limit 最高为 5,000 时会按 500 运行，并在 limitClamp 中报告截断；超过 5,000 则拒绝调用。文本摘要中的每站点数量、总数和峰值仅涵盖当前返回页
• 查询近期事件前，请使用 gdelt_list_tv_stations 检查站点的日期范围

---

gdelt_get_tv_clips _工具

• 每次调用最多获取 3,000 个片段，可按相关性、日期降序或日期升序排序；maxRecords 最高为 30,000 时会按 3,000 运行，并在 limitClamp 中报告截断；超过 30,000 则拒绝调用
• 每个片段包含：节目名称、station 和 stationName（按 gdelt_search_tv 中的方式解析，因此系列的 station 可直接传入 stations）、播出时间戳、15 秒的文字稿摘录、Archive.org 直接链接，以及可选缩略图
• 服务会请求整点小时的数据，因此窗口宽度不限；明确指定 startDatetime/endDatetime 窗口外的片段会被丢弃，并在通知中计数（使用 timespan 调用时不会丢弃任何片段）
• 响应会尽可能包含不超过 48,000 字节的数据；其余片段会计入 withheldCount，而 continuationWindows 会提供可重新查询这些片段的日期窗口（按 archiveUrl 去重）。3,000 是硬性上限，不是分页大小，因此要超过此上限，只能缩小日期窗口

---

gdelt_get_tv_context _工具

• 返回与查询共同出现频率最高的非停用词
• 词语和分数来自 GDELT 对最相关的 200 个匹配片段的抽样，而非全部报道；每个非空响应都会在 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 工具共用请求节流器：每次只允许一个请求在途，频率为每 5 秒 1 个请求；收到任何限流响应后都会退避（从 5 秒开始，每次翻倍，最长 60 秒）
• 使用结构化的 stations 数组，而非原始 TV 查询语法
• 首次下载后将 GKG 主题查询表保存在内存中

便于 Agent 使用的输出：

• 每个响应都回显查询内容：原始查询和应用的时间范围，以便调用链式传递，无需重新推导参数
• 使用带类型的序列 label 字段（"Volume Intensity"、"Average Tone"、语言／国家名称），而非按位置排列的数组
• 站点元数据包含 isActive 布尔值和 ISO 8601 日期
• 无匹配结果时，仍返回常规输出结构，其中数组为空，并通过 notice 说明如何扩大查询范围

开始使用

公共托管实例

公共实例位于 https://gdelt.caseyjhand.com/mcp，无需安装。将任意 MCP 客户端通过 Streamable HTTP 指向该实例：

{
  "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 schema 验证所有配置。主要环境变量：

变量	描述	默认值
GDELT_BASE_URL	覆盖 DOC 和 TV API 使用的 GDELT API 基础 URL。	https://api.gdeltproject.org/api/v2
GDELT_REQUEST_DELAY_MS	GDELT 请求之间的最小间隔毫秒数（强制执行每 5 秒 1 个请求的限制）。	5300
GDELT_REQUEST_TIMEOUT_MS	单个 GDELT 请求的截止时间（包含重试的调用最长不超过此时间的两倍）。	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 插桩。	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 和 TV API 及 GKG 主题查询的 9 个工具。
src/services/gdelt	封装 DOC 和 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。