# gdelt-mcp-server MCP server connecting agents to GDELT Project APIs for global news and US television caption analysis. It tracks media spikes, sentiment, and quotes. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6 - Author: cyanheads - License: Apache-2.0 · policy=link-only · description only; the file stays with the author - Source: https://github.com/cyanheads/gdelt-mcp-server - Updated: 2026-10-17 - HTML: https://affpapa.org/en/nevibecode/mcp/gdelt-mcp-server ## What it 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`. ## Requirements - Needs: Node.js (commands run via npx) - Remote server: `https://gdelt.caseyjhand.com/mcp` - Environment variables: `GDELT_BASE_URL`, `GDELT_REQUEST_DELAY_MS`, `GDELT_REQUEST_TIMEOUT_MS`, `MCP_LOG_LEVEL`, `MCP_TRANSPORT_TYPE`, `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_ENDPOINT_PATH`, `MCP_AUTH_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) 1. **Platform CLI: remote server** ```bash claude mcp add --transport http gdelt-mcp-server https://gdelt.caseyjhand.com/mcp ``` 2. **Platform CLI** ```bash claude mcp add --env GDELT_BASE_URL= --env GDELT_REQUEST_DELAY_MS= --env GDELT_REQUEST_TIMEOUT_MS= --env MCP_LOG_LEVEL= --env MCP_TRANSPORT_TYPE= --transport stdio gdelt-mcp-server -- npx -y @cyanheads/gdelt-mcp-server ``` Replace <…> with your own values. 4 more environment variables are in the server README ### Codex 1. **Platform CLI: remote server** ```bash codex mcp add gdelt-mcp-server --url https://gdelt.caseyjhand.com/mcp ``` 2. **Platform CLI** ```bash codex mcp add gdelt-mcp-server --env GDELT_BASE_URL= --env GDELT_REQUEST_DELAY_MS= --env GDELT_REQUEST_TIMEOUT_MS= --env MCP_LOG_LEVEL= --env MCP_TRANSPORT_TYPE= -- npx -y @cyanheads/gdelt-mcp-server ``` Replace <…> with your own values. 4 more environment variables are in the server README ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "gdelt-mcp-server": { "url": "https://gdelt.caseyjhand.com/mcp" } } } ``` File `.cursor/mcp.json`: ```json { "mcpServers": { "gdelt-mcp-server": { "command": "npx", "args": [ "-y", "@cyanheads/gdelt-mcp-server" ], "env": { "GDELT_BASE_URL": "", "GDELT_REQUEST_DELAY_MS": "", "GDELT_REQUEST_TIMEOUT_MS": "", "MCP_LOG_LEVEL": "", "MCP_TRANSPORT_TYPE": "" } } } } ``` Replace <…> with your own values. 4 more environment variables are in the server README ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "gdelt-mcp-server": { "type": "http", "url": "https://gdelt.caseyjhand.com/mcp" } } } ``` File `.vscode/mcp.json`: ```json { "servers": { "gdelt-mcp-server": { "type": "stdio", "command": "npx", "args": [ "-y", "@cyanheads/gdelt-mcp-server" ], "env": { "GDELT_BASE_URL": "", "GDELT_REQUEST_DELAY_MS": "", "GDELT_REQUEST_TIMEOUT_MS": "", "MCP_LOG_LEVEL": "", "MCP_TRANSPORT_TYPE": "" } } } } ``` Replace <…> with your own values. 4 more environment variables are in the server README ### Gemini CLI 1. **Platform CLI: remote server** ```bash gemini mcp add -t http gdelt-mcp-server https://gdelt.caseyjhand.com/mcp ``` 2. **Platform CLI** ```bash gemini mcp add -e GDELT_BASE_URL= -e GDELT_REQUEST_DELAY_MS= -e GDELT_REQUEST_TIMEOUT_MS= -e MCP_LOG_LEVEL= -e MCP_TRANSPORT_TYPE= gdelt-mcp-server npx -y @cyanheads/gdelt-mcp-server ``` Replace <…> with your own values. 4 more environment variables are in the server README ## When to use it - 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 - 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` ## Similar - [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609 - [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89899 - [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730 - [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40459 - [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27844 - [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49863 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md