MCP Server URL: https://gdelt-cloud-mcp.fastmcp.app/mcpUse this URL to connect your MCP client to GDELT Cloud.
Quick Setup
Get connected to GDELT data through MCP in just a few steps.
Verify your plan
MCP access requires Scout (49/mo),∗∗Analyst∗∗(499/mo), or Professional ($1,999/mo) planCheck your plan at gdeltcloud.com/dashboard/settings Generate API key
Go to Settings → API Keys and create a new keyCopy your API key immediately - it’s only shown once!
Choose your integration
Select based on your use case:FastMCP
Direct Python integration for custom agents
LangChain
Build AI agents with LangChain framework
Connect and query
Use the examples below to connect and start querying GDELT data
Configuration Examples
FastMCP (Python)
LangChain
from fastmcp import Client
from fastmcp.client.auth import BearerAuth
import os
# API key authentication
async with Client(
"https://gdelt-cloud-mcp.fastmcp.app/mcp",
auth=BearerAuth(token=os.environ["GDELT_API_KEY"])
) as client:
# List available tools
tools = await client.get_tools()
print(f"Available tools: {[t.name for t in tools]}")
# Fetch schemas resource
schemas = await client.read_resource(
"gdelt://resources/schemas"
)
print(schemas.text)
# Execute a query
result = await client.call_tool(
"execute_query",
arguments={
"sql": """
SELECT day, actor1_name, actor2_name, event_code
FROM gdelt_events
WHERE day >= '2025-04-01'
AND action_geo_country_code = 'USA'
LIMIT 10
"""
}
)
print(result)
Store your API key in a .env file:GDELT_API_KEY=gdelt_sk_your_api_key_here
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
import os
async def main():
# Initialize MCP client with GDELT Cloud server
mcp_client = MultiServerMCPClient({
"gdelt-cloud": {
"transport": "streamable_http",
"url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
"headers": {
"Authorization": f"Bearer {os.getenv('GDELT_API_KEY')}"
}
}
})
# Fetch GDELT tools
gdelt_tools = await mcp_client.get_tools(server_name="gdelt-cloud")
print(f"Loaded {len(gdelt_tools)} GDELT tools")
# Fetch GDELT core system prompt
messages = await mcp_client.get_prompt("gdelt-cloud", "gdelt_system_prompt")
gdelt_core_prompt = "\n\n".join(msg.content for msg in messages)
# Create LLM and agent
llm = ChatOpenAI(model="gpt-4", temperature=0)
agent = create_agent(
model=llm,
tools=gdelt_tools,
system_prompt=f"You are a GDELT analyst.\n\n{gdelt_core_prompt}"
)
# Run query
result = await agent.ainvoke({
"messages": [{
"role": "user",
"content": "What protests happened in France this week?"
}]
})
print(result["messages"][-1]["content"])
import asyncio
asyncio.run(main())
Available MCP Capabilities
The GDELT MCP server provides three types of capabilities:
Validate and optimize SQL queries before executionresult = await client.call_tool(
"prepare_query",
arguments={
"sql": "SELECT * FROM gdelt_events WHERE day >= '2025-04-01' LIMIT 10"
}
)
Execute validated SQL queries against GDELT dataresult = await client.call_tool(
"execute_query",
arguments={
"sql": "SELECT day, actor1_name FROM gdelt_events LIMIT 10"
}
)
Format SQL queries for user review (used in alert creation)result = await client.call_tool(
"present_sql",
arguments={
"sql": "SELECT * FROM gdelt_events WHERE event_code = '14'"
}
)
Fetch CAMEO codes and schema documentationresult = await client.call_tool(
"get_resource",
arguments={
"uri": "gdelt://resources/codes"
}
)
Resources
Access static documentation via resource URIs:
gdelt://resources/schemas - Database schema documentationgdelt://resources/codes - CAMEO taxonomy (country codes, event codes, themes, etc.)
Prompts
gdelt_system_prompt - Core system prompt for GDELT query assistance
Example Queries
Try these natural language queries with your AI agent:
What protests happened in France in the last week?
Next Steps
