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.

MCP Server URL: https://gdelt-cloud-mcp.fastmcp.app/mcp

​
Quick Setup

1

Generate an API key

Go to Settings → API Keys and create a key on a plan with API/MCP access.
Copy your API key immediately. It is shown only once.
2

Connect your MCP client

Use bearer authentication with your gdelt_sk_... key.
3

Use Progressive Discovery

Call gdelt_cloud_tool_list, inspect with gdelt_cloud_tool_get, then execute with gdelt_cloud_tool_call.

​
FastMCP Example

from fastmcp import Client
from fastmcp.client.auth import BearerAuth
import os

async with Client(
    "https://gdelt-cloud-mcp.fastmcp.app/mcp",
    auth=BearerAuth(token=os.environ["GDELT_API_KEY"]),
) as client:
    catalog = await client.call_tool("gdelt_cloud_tool_list", {})
    print([tool["name"] for tool in catalog["tools"]])

    schema = await client.call_tool(
        "gdelt_cloud_tool_get",
        {"tool_name": "search_events"},
    )
    print(schema["tool"]["description"])

    result = await client.call_tool(
        "gdelt_cloud_tool_call",
        {
            "tool_name": "search_events",
            "tool_arguments": {
                "event_family": "conflict",
                "country": "Lebanon",
                "has_fatalities": True,
                "start_date": "2026-04-11",
                "end_date": "2026-04-17",
                "sort": "significance",
                "limit": 5,
            },
        },
    )
    print(result)

​
LangChain / LangGraph Pattern

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
import os

mcp_client = MultiServerMCPClient({
    "gdelt-cloud": {
        "transport": "streamable_http",
        "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
        "headers": {
            "Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"
        },
    }
})

tools = await mcp_client.get_tools(server_name="gdelt-cloud")
messages = await mcp_client.get_prompt("gdelt-cloud", "gdelt_system_prompt")
gdelt_prompt = "\n\n".join(str(msg.content) for msg in messages)

agent = create_agent(
    model=ChatOpenAI(model="gpt-5.4-mini", temperature=0),
    tools=tools,
    system_prompt=gdelt_prompt,
)

result = await agent.ainvoke({
    "messages": [{
        "role": "user",
        "content": "Show fatal conflict Events in Lebanon this week with citations."
    }]
})

​
First Calls To Try

Event and Story list/summary tools default to confidence_profile=precise for clean, analyst-ready results. Add confidence_profile=loose only when exhaustive/raw retrieval is required.

​
Protests By Day

{
  "tool_name": "summarize_events",
  "tool_arguments": {
    "category": "Protests",
    "country": "India",
    "group_by": "date",
    "start_date": "2026-03-19",
    "end_date": "2026-04-17"
  }
}

​
New Data Center Projects In Asia

{
  "tool_name": "search_stories",
  "tool_arguments": {
    "continent": "Asia",
    "search": "new data center projects",
    "article_count_min": 1,
    "start_date": "2026-04-04",
    "end_date": "2026-04-17",
    "sort": "significance"
  }
}

​
Infrastructure Events

{
  "tool_name": "search_events",
  "tool_arguments": {
    "event_family": "cameoplus",
    "domain": "INFRASTRUCTURE",
    "country": "United States",
    "start_date": "2026-04-04",
    "end_date": "2026-04-17",
    "sort": "significance"
  }
}

​
Next Steps

Progressive Discovery

Learn the wrapper flow and public catalog.

GDELT v2 Tools

See Events, Stories, Entities, and geo discovery.

External Tools

Use macro finance, prediction markets, and web research as enrichment.

LangChain Integration

Build custom agents with GDELT Cloud MCP.