GDELT Cloud Docs — Global Event Data API & MCP

Overview

GDELT Cloud MCP uses a Progressive Discovery interface. Agents do not call GDELT Cloud product tools directly. They first discover the catalog, inspect exact schemas, then execute a named tool through a single wrapper. This keeps the public MCP surface small while still giving agents rich tool descriptions and typed parameter guidance.

What The Agent Actually Sees

The public MCP surface is intentionally small. Agents see wrapper tools, not every nested product operation as a separate top-level tool.

Category	Top-Level Wrapper Tools Agents See
GDELT Cloud	`gdelt_cloud_tool_list`, `gdelt_cloud_tool_get`, `gdelt_cloud_tool_call`
Macro finance	`macro_finance_tool_list`, `macro_finance_tool_get`, `macro_finance_tool_call`
Prediction markets	`prediction_market_tool_list`, `prediction_market_tool_get`, `prediction_market_tool_call`
Web research	`web_research_tool_list`, `web_research_tool_get`, `web_research_tool_call`

Inside each *_tool_call, the agent passes a nested tool_name and tool_arguments.

Public GDELT Cloud MCP Tools

The MCP server exposes these three GDELT Cloud wrapper tools:

Tool	Purpose
`gdelt_cloud_tool_list`	List the public v2 GDELT Cloud tools and when to use them.
`gdelt_cloud_tool_get`	Fetch exact schema, descriptions, enums, and parameter guidance for one or more tools.
`gdelt_cloud_tool_call`	Execute a named v2 GDELT Cloud tool with nested `tool_arguments`.

The legacy v1 MCP tool names are no longer exposed. v1 REST endpoints remain supported for direct API users, but agents should use the v2 MCP catalog documented here.

Workflow

Discover

Call gdelt_cloud_tool_list to see the available v2 GDELT Cloud product tools.

Inspect

Call gdelt_cloud_tool_get before first use of a tool. The schema contains practical descriptions, enum values, default behavior, and guidance on how analysts should use each parameter.

Execute

Call gdelt_cloud_tool_call with tool_name and nested tool_arguments.

Event, Story, and Entity search tools default to the exact past 24 hours. Agents should narrow with developer-facing filters such as category, subcategory, civilian_targeting, country/region/continent filters, date windows, sort, and pagination.

Example

{
  "tool_name": "search_events",
  "tool_arguments": {
    "category": "Battles",
    "subcategory": "Armed clash",
    "country": "Lebanon",
    "has_fatalities": true,
    "days": 7,
    "sort": "significance",
    "limit": 10
  }
}

v2 Catalog

v2 Tool	Use When
`search_events`	You need structured Conflict or CAMEO+ Event cards.
`summarize_events`	You need dashboard-ready Event counts or trends.
`get_event`	You know an Event ID and need the full card.
`search_stories`	You need clustered narrative Stories and article evidence.
`summarize_stories`	You need Story rollups by date, geography, category, or subcategory.
`get_story`	You know a Story ID and need details plus top articles.
`get_story_articles`	You need the full paginated article list for a Story.
`search_entities`	You need to discover linked people or organizations.
`get_entity`	You know an Entity ID and need its linked Stories and Events.
`list_admin1`	You need valid state/province/admin1 names for one country.

External Enrichment Categories

GDELT Cloud structured Events and Stories should anchor the analysis. External MCP categories are encouraged as complements:

Category	Use For
`macro_finance_*`	Quotes, FX, commodities, rates, historical series, and macro indicators.
`prediction_market_*`	Kalshi-backed event and market search, contract details, probabilities, status, and public market URLs when available.
`web_research_*`	Corroboration, official statements, specialist sources, and reading source-article pages.

For geopolitical, macro-finance, supply-chain, and location-security analysis, use GDELT Cloud first to establish the structured signal, then enrich or verify with macro finance, prediction markets, and web research where relevant.

External Nested Tools

Category	Nested Tools
Prediction markets	`SEARCH_RELEVANT_MARKETS`, `SEARCH_EVENTS`, `SEARCH_MARKETS`, `GET_MARKET`
Web research	`SEARCH_WEB`, `EXTRACT_WEB_PAGES`
Macro finance	Discover current macro-finance provider-backed quote, historical series, FX, commodities, rates, and economic-indicator tools with `macro_finance_tool_list`.

The web-research category exposes only SEARCH_WEB and EXTRACT_WEB_PAGES; crawl and map operations are intentionally not public.

Overview

Tools

Resources

Skills

Prompts

Integrations

Progressive Discovery

Overview

What The Agent Actually Sees

Public GDELT Cloud MCP Tools

Workflow

Example

v2 Catalog

External Enrichment Categories

External Nested Tools

​Overview

​What The Agent Actually Sees

​Public GDELT Cloud MCP Tools

​Workflow

​Example

​v2 Catalog

​External Enrichment Categories

​External Nested Tools

Overview

What The Agent Actually Sees

Public GDELT Cloud MCP Tools

Workflow

Example

v2 Catalog

External Enrichment Categories

External Nested Tools