# gdelt-mcp-server MCP server

Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-cyanheads-gdelt-mcp-server
- Repository: https://github.com/cyanheads/gdelt-mcp-server

## Install
- Command: `npx -y @cyanheads/gdelt-mcp-server`
- Endpoint: https://gdelt.caseyjhand.com/mcp
- Auth: Not captured

## Setup notes
- Package: Npm @cyanheads/gdelt-mcp-server v0.1.8
- Environment variable: MCP_LOG_LEVEL (default info)
- Package: Npm @cyanheads/gdelt-mcp-server v0.1.8
- Environment variable: MCP_HTTP_HOST (default 127.0.0.1)
- Environment variable: MCP_HTTP_PORT (default 3010)
- Environment variable: MCP_HTTP_ENDPOINT_PATH (default /mcp)
- Environment variable: MCP_AUTH_MODE (default none)
- Environment variable: MCP_LOG_LEVEL (default info)
- Remote endpoint: https://gdelt.caseyjhand.com/mcp

## Tools
- gdelt_search_articles (Search GDELT Articles) - Search the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Returns up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL. Query supports full GDELT syntax: phrases ("bird flu"), boolean OR ((flu OR pandemic)), source country (sourcecountry:china), source language (sourcelang:spanish), domain (domain:who.int), GKG theme (theme:DISEASE_OUTBREAK), tone filter (tone<-5 for negative), proximity (near20:"flu virus"), and repeat (repeat3:"outbreak"). Note: this API covers only the most recent 3 months — use gdelt_search_tv for historical TV transcripts back to 2009. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_coverage_timeline (Get GDELT Coverage Timeline) - Retrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. Use mode "volume" for normalized coverage intensity (% of all global coverage per timestep). Use mode "volume_with_articles" for the same signal plus the top articles that drove each spike — this is the primary signal-detection mode: a single call reveals both the spike and its cause, avoiding a follow-up gdelt_search_articles call. Use mode "tone" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). Date resolution is automatically chosen based on timespan: hours for short windows, days for longer ones. Note: DOC API covers only the last 3 months. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_tone_distribution (Get GDELT Tone Distribution) - Get the tonal distribution of articles matching a query as a histogram (bins approximately -30 to +30). Unlike a single average tone score, the histogram reveals whether coverage is uniformly negative, bimodal (some articles extremely positive and some extremely negative), or clustered near neutral. Each bin includes representative article URLs. Distinct from gdelt_get_coverage_timeline (mode: tone) — this is a snapshot distribution across all matching articles, not a time series. Use gdelt_get_coverage_timeline with mode "tone" to see how sentiment shifted over time. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_coverage_breakdown (Get GDELT Coverage Breakdown) - Break down news coverage volume over time by source language or source country, returning a multi-series time series (one series per language or country). Shows which countries or languages drove early vs. late coverage — useful for tracing how a story propagated geographically or across language communities. Returns up to 10 series by total volume; remaining series are aggregated into an "Other" bucket. Use breakdownBy "country" with the signal-detection chain to map geographic attention, or "language" to detect non-English media surges. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_search_tv (Search GDELT TV News) - Search US television news closed captions (2009–October 2024, 150+ stations) for spoken mentions of a query. Returns a normalized per-station time series showing relative airtime devoted to the topic. Use the stations parameter to compare specific networks (e.g. ["CNN", "FOXNEWS", "MSNBC"]); omit to get combined national coverage. TV query also supports in-query operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper 360", context:"vaccine". Important: most station monitoring ended October 2024 — use gdelt_list_tv_stations to verify active date ranges before querying recent events. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_tv_clips (Get GDELT TV Clips) - Retrieve the top matching TV news clips (up to 3,000) for a query from the Internet Archive's Television News Archive. Each clip includes show name, station, air timestamp, a 15-second transcript excerpt, and a direct link to view the full one-minute clip. Use after gdelt_search_tv to read the actual transcript content driving a coverage spike. Archive coverage spans 2009–October 2024. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_tv_context (Get GDELT TV Context) - Get the top co-occurring words and phrases from TV news clips matching a query — the vocabulary framing a topic on television. Returns the most frequent non-stopword terms from matching clips, with relative frequency scores (0–100, where 100 = the query term itself). Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms. TV data spans 2009–October 2024. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_get_tv_trending (Get GDELT TV Trending) - Retrieve trending topics, keywords, and phrases currently dominating US television news across national networks. No query required — returns the top memes of the present news cycle. Updated every 15 minutes. Note: the GDELT TV archive feed stopped updating around October 2024; results from this endpoint reflect that most-recent archived data rather than a live feed. Endpoint: https://gdelt.caseyjhand.com/mcp
- gdelt_list_tv_stations (List GDELT TV Stations) - List all television stations available for TV search with their market, network, monitoring start date, and monitoring end date. Stations with an end date within the last 24 hours are flagged as active; stations with earlier end dates are discontinued. Use before querying to verify a station was active during the target time period, or to discover valid station IDs for the stations parameter in other TV tools. Most station monitoring ended October 2024 when the Internet Archive TV feed stopped updating. Endpoint: https://gdelt.caseyjhand.com/mcp

## Resources
Not captured

## Prompts
Not captured

## Metadata
- Owner: io.github.cyanheads
- Version: 0.1.8
- Runtime: Npm
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Jun 4, 2026
- Source: https://registry.modelcontextprotocol.io