gdelt-mcp-server — Claude Code MCP server: setup guide
MCP server connecting agents to GDELT Project APIs for global news and US television caption analysis. It tracks media spikes, sentiment, and quotes.
claude mcp add --transport http gdelt-mcp-server https://gdelt.caseyjhand.com/mcpWhat gdelt-mcp-server does
This server exposes 9 tools for GDELT data retrieval. The agent can inspect international news published during the past 3 months across 65+ languages, alongside closed captions from 150+ US television networks covering 2009 through October 2024. Handlers like gdelt_search_articles support filters by domain, language, or GKG themes, while gdelt_get_coverage_timeline produces coverage timelines and tone tracking.
Payload size is constrained by a 48,000-byte cap per response. Article searches fetch up to 250 items at a time; anything beyond the byte limit is cut, accompanied by date ranges to query subsequently. Narrowing the query date range is mandatory to retrieve more stories, because the tool rejects any call where maxRecords exceeds 2,500.
Broadcast monitoring functions include gdelt_get_tv_clips, which returns transcript snippets alongside Internet Archive playback URLs. You can connect through the public HTTP endpoint at https://gdelt.caseyjhand.com/mcp or run a local stdio instance with npx.
What it helps with
- query global news articles across 65+ languages from the past 3 months
- plot media volume time series and track coverage sentiment
- inspect tone histograms from -30 to +30 to detect polarization
- search historical US television closed captions across 150+ stations
Example prompts for the agent
- Search recent international news covering semiconductor export controls using
gdelt_search_articles - Generate a timeline of coverage volume and sentiment shifts with
gdelt_get_coverage_timeline - Retrieve television transcript snippets mentioning space exploration via
gdelt_get_tv_clips
How to install gdelt-mcp-server
1Platform CLI: remote server
claude mcp add --transport http gdelt-mcp-server https://gdelt.caseyjhand.com/mcp2Platform CLI
claude mcp add --env GDELT_BASE_URL=<GDELT_BASE_URL> --env GDELT_REQUEST_DELAY_MS=<GDELT_REQUEST_DELAY_MS> --env GDELT_REQUEST_TIMEOUT_MS=<GDELT_REQUEST_TIMEOUT_MS> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --transport stdio gdelt-mcp-server -- npx -y @cyanheads/gdelt-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
1Platform CLI: remote server
codex mcp add gdelt-mcp-server --url https://gdelt.caseyjhand.com/mcp2Platform CLI
codex mcp add gdelt-mcp-server --env GDELT_BASE_URL=<GDELT_BASE_URL> --env GDELT_REQUEST_DELAY_MS=<GDELT_REQUEST_DELAY_MS> --env GDELT_REQUEST_TIMEOUT_MS=<GDELT_REQUEST_TIMEOUT_MS> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> -- npx -y @cyanheads/gdelt-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"mcpServers": {
"gdelt-mcp-server": {
"url": "https://gdelt.caseyjhand.com/mcp"
}
}
}{
"mcpServers": {
"gdelt-mcp-server": {
"command": "npx",
"args": [
"-y",
"@cyanheads/gdelt-mcp-server"
],
"env": {
"GDELT_BASE_URL": "<GDELT_BASE_URL>",
"GDELT_REQUEST_DELAY_MS": "<GDELT_REQUEST_DELAY_MS>",
"GDELT_REQUEST_TIMEOUT_MS": "<GDELT_REQUEST_TIMEOUT_MS>",
"MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
"MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"servers": {
"gdelt-mcp-server": {
"type": "http",
"url": "https://gdelt.caseyjhand.com/mcp"
}
}
}{
"servers": {
"gdelt-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cyanheads/gdelt-mcp-server"
],
"env": {
"GDELT_BASE_URL": "<GDELT_BASE_URL>",
"GDELT_REQUEST_DELAY_MS": "<GDELT_REQUEST_DELAY_MS>",
"GDELT_REQUEST_TIMEOUT_MS": "<GDELT_REQUEST_TIMEOUT_MS>",
"MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
"MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
1Platform CLI: remote server
gemini mcp add -t http gdelt-mcp-server https://gdelt.caseyjhand.com/mcp2Platform CLI
gemini mcp add -e GDELT_BASE_URL=<GDELT_BASE_URL> -e GDELT_REQUEST_DELAY_MS=<GDELT_REQUEST_DELAY_MS> -e GDELT_REQUEST_TIMEOUT_MS=<GDELT_REQUEST_TIMEOUT_MS> -e MCP_LOG_LEVEL=<MCP_LOG_LEVEL> -e MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> gdelt-mcp-server npx -y @cyanheads/gdelt-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about gdelt-mcp-server
How to install gdelt-mcp-server in Claude Code?
Run claude mcp add --transport http gdelt-mcp-server https://gdelt.caseyjhand.com/mcp to connect to the public hosted endpoint.
What does gdelt-mcp-server do?
It grants AI models direct query access to GDELT APIs covering 3 months of global articles and 15 years of US TV captions. Models can analyze media volume, examine article sentiment, and verify quotes.
What is the article query limit?
gdelt_search_articles caps output at 250 records fitting within a 48,000-byte budget. When more matches exist, it outputs continuation date windows to paginate subsequent calls.
