GDELT Cloud MCP Server

什么是 GDELT Cloud MCP Server？

GDELT Cloud MCP Server 是 GDELT Cloud 的托管 MCP 端点，Claude、ChatGPT、Codex 和自定义智能体可以借助它查询结构化的地缘政治事件、聚类新闻报道以及相关的人物、组织和地点，数据与 GDELT Cloud REST API 完全一致。

GDELT Cloud 将公开的 GDELT 文章流转化为结构化数据库。事件按其自有分类体系（CAMEO+ 和 Conflict 类别）编码，包含行为者、地理位置、来源证据和指标；Stories 将其背后的文章聚类；实体则把报道与相关人物和组织关联起来。它还把公开登记数据接入同一实体主干，包括 SEC filings、GLEIF、USAspending、FRED、Global Energy Monitor 和 Epoch AI。文档称 MCP 服务器与 API 调用相同的服务函数，因此通过 MCP 得到的答案也可以用 curl 得到。

如何使用 GDELT Cloud MCP Server？

你需要一个 GDELT Cloud 账户。服务器 URL 为：

https://mcp.gdeltcloud.com/mcp

该服务器使用 Streamable HTTP。Claude 和 ChatGPT 在浏览器中通过 OAuth 登录；使用 bearer 认证的客户端需要在 gdeltcloud.com/api-keys 创建的 API 密钥（以 gdelt_sk_ 开头）。你的套餐决定哪些端点可用，与 REST 完全相同。

Claude Code

claude mcp add --transport http gdelt-cloud https://mcp.gdeltcloud.com/mcp

然后在会话中打开 /mcp 并按照 OAuth 登录流程操作。GDELT Cloud 还为 Claude Code、Codex 和 Cursor 提供插件（GitHub 上的 gdelt-cloud/plugins），可一次性添加此服务器、一个文档服务器和八个技能。

Claude Desktop 和 claude.ai

进入 Settings → Connectors → Add custom connector，粘贴服务器 URL，使用 GDELT Cloud 账户登录并批准连接。无需 API 密钥。

Cursor

将服务器添加到 ~/.cursor/mcp.json，并在 Cursor 的 MCP 设置中完成认证：

{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://mcp.gdeltcloud.com/mcp"
    }
  }
}

VS Code

添加到 .vscode/mcp.json；服务器首次运行时 VS Code 会启动 OAuth 登录：

{
  "servers": {
    "gdelt-cloud": {
      "type": "http",
      "url": "https://mcp.gdeltcloud.com/mcp"
    }
  }
}

Codex（API 密钥）

GDELT Cloud 文档中的 Codex 配置从环境变量读取 bearer 密钥：

export GDELT_API_KEY=gdelt_sk_...
codex mcp add gdelt-cloud \
  --url https://mcp.gdeltcloud.com/mcp \
  --bearer-token-env-var GDELT_API_KEY

bearer_token_env_var 填写的是变量名，而不是密钥本身。

GDELT Cloud MCP Server 的主要功能

• 官方远程服务器，数据和权限与 GDELT Cloud REST API v2 相同。
• 据文档介绍，提供 116 个带类型参数的命名领域操作，覆盖新闻、身份、国家、Situations、Monitors 以及专题数据集（媒体倾向、设施、filings、GLEIF、能源、AI 算力、宏观、风险筛查、海事 AIS）。
• 先做实体解析：unified_entity_search 将名称解析为候选 ID，search_entities 发现某段时间或某地报道中出现的对象。
• 免费且不计量的发现辅助工具：get_data_catalog、get_parameter_options 和 get_event_taxonomy。
• Monitors：先预览一个持续性问题，再保存为定时运行，通过邮件或签名 webhook 推送；create_monitor、update_monitor 等写入操作需要宿主批准。
• response_mode="compact"（默认）或 "full"，保留记录链接、证据和覆盖范围，方便智能体引用来源。
• 权限错误会指明所需的套餐标志，而不是返回一个看起来像缺失数据的空结果。

GDELT Cloud MCP Server 的使用场景

• 国家简报："尼日利亚过去 7 天发生了什么变化？按类别分组事件并引用相关报道。"
• 实体调查：解析一家公司，然后追踪其相关事件、报道、媒体倾向、SEC filings 和设施。
• 持续事态：跟踪一个 Situation，它汇集了关于某一发展中事件的报道和编码事件。
• 预警："为该地区港口附近的抗议活动设置一个 Monitor，并把匹配结果发送到我的 webhook。"先预览，再确认。
• 供应链与资产研究：搜索发电厂、矿山、港口和数据中心，查看所有权和来源观测记录。

GDELT Cloud MCP Server 常见问题排查

• 工具没有出现：客户端已连接但认证失败。检查密钥是否为有效的 gdelt_sk_ 密钥、是否已在 gdeltcloud.com/api-keys 被撤销，或重新进行 OAuth 登录。
• 调用返回套餐错误：该端点不在你的套餐内。错误信息会指明所需的标志。
• 模型编造了参数：让它先获取端点说明；服务器会拒绝未知的过滤条件，而不是忽略它们。
• Codex 返回 401：bearer_token_env_var 被设成了密钥本身，而不是变量名。
• 旧工具或旧端点：如果客户端仍保存着旧端点，请更新为 https://mcp.gdeltcloud.com/mcp，重新登录并刷新工具列表。