MCP Server URL: https://gdelt-cloud-mcp.fastmcp.app/mcp
Quick Setup
Generate API key
Go to Settings → API Keys and create a new key.Copy your API key immediately — it’s only shown once!
Choose your integration
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
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]}")
# Discover today's top stories
result = await client.call_tool(
"get_media_events",
arguments={"days": 1, "limit": 5, "detail": "summary"}
)
print(result)
# Deep-dive into a cluster
result = await client.call_tool(
"get_media_event_cluster",
arguments={"cluster_id": "abc123", "detail": "summary"}
)
print(result)
# Look up an entity
result = await client.call_tool(
"get_entity",
arguments={
"canonical_name": "elon musk",
"type": "person",
"days": 7,
"detail": "summary"
}
)
print(result)
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
import os
async def main():
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 system prompt
messages = await mcp_client.get_prompt("gdelt-cloud", "gdelt_system_prompt")
gdelt_prompt = "\n\n".join(msg.content for msg in messages)
# Create 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_prompt}"
)
result = await agent.ainvoke({
"messages": [{"role": "user", "content": "What are today's top stories?"}]
})
print(result["messages"][-1]["content"])
import asyncio
asyncio.run(main())
Available MCP Capabilities
Wikipedia-linked entity profile with linked stories and co-occurrences.result = await client.call_tool(
"get_entity",
arguments={"canonical_name": "donald trump", "type": "person", "days": 7, "detail": "summary"}
)
News domain profile with stats, top entities, and recent articles.result = await client.call_tool(
"get_domain",
arguments={"domain": "reuters.com", "days": 7}
)
Resources
Access CAMEO code references via resource URIs:
gdelt://codes/cameo-country — Country codes for actor filteringgdelt://codes/cameo-event — Event type codes (01–20)gdelt://codes/goldstein-scale — Goldstein scale reference
Prompts
gdelt_system_prompt — Core system prompt for GDELT analysis
Next Steps
