Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

GDELT Cloud MCP uses a Progressive Discovery interface. Agents do not call GDELT 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.
CategoryTop-Level Wrapper Tools Agents See
GDELT Cloudgdelt_cloud_tool_list, gdelt_cloud_tool_get, gdelt_cloud_tool_call
Macro financemacro_finance_tool_list, macro_finance_tool_get, macro_finance_tool_call
Prediction marketsprediction_market_tool_list, prediction_market_tool_get, prediction_market_tool_call
Web researchweb_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 MCP Tools

The MCP server exposes these three GDELT wrapper tools:
ToolPurpose
gdelt_cloud_tool_listList the public v2 GDELT Cloud tools and when to use them.
gdelt_cloud_tool_getFetch exact schema, descriptions, enums, and parameter guidance for one or more tools.
gdelt_cloud_tool_callExecute 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

1

Discover

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

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.
3

Execute

Call gdelt_cloud_tool_call with tool_name and nested tool_arguments.
Event and Story search/summary tools default to confidence_profile=precise, which filters to analyst-ready results and collapses obvious Story duplicates. Use confidence_profile=loose only when the user needs exhaustive/raw retrieval.

​
Example

{
  "tool_name": "search_events",
  "tool_arguments": {
    "event_family": "conflict",
    "country": "Lebanon",
    "has_fatalities": true,
    "days": 7,
    "sort": "significance",
    "limit": 10
  }
}

​
v2 Catalog

v2 ToolUse When
search_eventsYou need structured Conflict or CAMEO+ Event cards.
summarize_eventsYou need dashboard-ready Event counts or trends.
get_eventYou know an Event ID and need the full card.
search_storiesYou need clustered narrative Stories and article evidence.
summarize_storiesYou need Story rollups by date, geography, category, or subcategory.
get_storyYou know a Story ID and need details plus top articles.
get_story_articlesYou need the full paginated article list for a Story.
search_entitiesYou need to discover linked people or organizations.
get_entityYou know an Entity ID and need its linked Stories and Events.
list_admin1You 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:
CategoryUse 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 first to establish the structured signal, then enrich or verify with macro finance, prediction markets, and web research where relevant.

​
External Nested Tools

CategoryNested Tools
Prediction marketsSEARCH_RELEVANT_MARKETS, SEARCH_EVENTS, SEARCH_MARKETS, GET_MARKET
Web researchSEARCH_WEB, EXTRACT_WEB_PAGES
Macro financeDiscover 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.