Skip to main content
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": {
                "category": "Battles",
                "subcategory": "Armed clash",
                "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_research_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, Story, and Entity search tools default to the exact past 24 hours. Narrow with geography, category, subcategory, civilian_targeting, date windows, and semantic search rather than public confidence modes.

​
Protests By Day

{
  "tool_name": "summarize_events",
  "tool_arguments": {
    "category": "Protests",
    "subcategory": "Peaceful protest",
    "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": {
    "category": "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 Cloud 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.