Gdelt MCP Server

@cyanheads/gdelt-mcp-server Search and analyze global news coverage and US television transcripts from the GDELT Project's real-time APIs via MCP. STDIO or Streamable HTTP. 10 Tools

Public Hosted Server: https://gdelt.caseyjhand.com/mcp

Overview

News and TV coverage analysis from the GDELT Project: global news in 65+ languages, and historical TV transcripts across 150+ stations, with coverage dates varying by station. Article search and relative timespan windows cover the last 3 months; explicit dates reach older windows in the coverage timeline's volume and tone modes, the language and country breakdowns, and the tone distribution. Search articles and clips, track coverage spikes, analyze tone, and compare coverage across languages, countries, stations, and shows.

Tools

Capability reference

gdelt_search_articles tool

• Full GDELT query syntax: phrases, boolean OR, exclusion, filter operators (sourcecountry:, sourcelang:, domain:, theme:, tone</tone>), proximity (near20:) and repetition (repeat3:) — gdelt_search_themes finds the identifiers theme: takes
• Configurable sort (relevance, dateDesc, dateAsc, toneDesc, toneAsc, hybridRel) and fetch count, up to 250 per call; larger maxRecords values clamp to 250 by default
• Returns URL, title, publication date, domain, language, source country, and social image URL
• Returns every fetched in-window article. At the provider ceiling, continuationWindows gives narrower date windows to re-query (de-duplicate by url). The ceiling is not a cursor; an indivisible window can still contain more matches than GDELT returns
• Articles outside an explicit startDatetime/endDatetime window are dropped, and the notice counts them

gdelt_get_coverage_timeline tool

• Four modes: volume (normalized % per timestep), volume_raw (matching-article counts with the monitored-article denominator norm), volume_with_articles (volume plus supplied top articles), and tone (average sentiment)
• Reference-bearing timesteps carry their first 3 links beside referenceCount, the number of references GDELT supplied, not all matching articles. points: [" "] selects named timesteps with every supplied link; GDELT's reference list itself is capped at ten
• Pages whole timesteps with offset and limit (default 10, cap 400); nextOffset retrieves the next page. Each series' pointCount and peak cover the full series on every page
• Smoothing accepts 0–30 timesteps. Width N > 1 returns trailing moving averages: the first N−1 source steps cannot produce a value, and peaks can appear later. In volume_raw, smoothing changes value, not norm
• Time range uses timespan (up to 3 months) or explicit startDatetime/endDatetime; date resolution (15min/hour/day) is inferred from returned intervals. In volume and tone modes an explicit window may predate the last 3 months; volume_raw and volume_with_articles cover only the last 3 months
• A points date matching no timestep, or an offset past the last timestep, is rejected with the valid values

gdelt_get_tone_distribution tool

• Histogram bins from approximately −30 to +30; each bin's count counts matching articles, while referenceCount counts supplied links. The default preview shows 3 links; bins: [ ] selects named bins with every supplied link. An unknown bin is rejected with the available bins
• Summary fields over the whole histogram: peakNegativeBin, peakPositiveBin, neutralPct (% of articles in the −2 to +2 range)
• Pages whole bins with offset and limit (default 10, cap 400), returning nextOffset when more remain. This is a snapshot across matching articles, unlike the tone timeline
• Time range uses timespan (up to 3 months) or explicit startDatetime/endDatetime, and an explicit window may predate the last 3 months

gdelt_get_coverage_breakdown tool

• Breaks down by language or country into a multi-series time series: the top 10 series by summed value, with every other series named in otherSeriesLabels
• series: [" "] returns only those series, complete, under selectedSeries; a label matching no series is rejected with the available labels
• Pages whole series with offset and limit (default 10, cap 75), returning nextOffset when more remain. Copy exact labels from the response for series selections
• Smoothing accepts 0–30 timesteps with the same moving-average disclosure as coverage timelines
• Time range uses timespan (up to 3 months) or explicit startDatetime/endDatetime, and an explicit window may predate the last 3 months
• Values are normalized shares of each source's media output, not article counts, so don't sum them across sources

gdelt_search_themes tool

• Searches the identifiers in GDELT's GKG theme lookup (59,315 themes); each match is the identifier, its listed count, and a paste-ready operator such as theme:TAX_DISEASE_OUTBREAK
• Case-insensitive, with no stemming or synonyms: words match parts of an identifier (cyberattack → CYBER_ATTACK, plant disease → TAX_PLANTDISEASE). If nothing matches, it retries once with a trailing s dropped (protests → PROTEST) and the notice says so
• Ranked by exact match, then listed count (a static prevalence figure, not a live article total), then identifier
• Pages with offset / limit (default 25, cap 100); larger limits clamp by default. nextOffset appears only when more matches remain, and an offset past a non-empty result fails offset_out_of_range
• Does not queue behind the DOC and TV rate limit

gdelt_search_tv tool

• Structured stations (e.g. ["CNN", "FOXNEWS"]) preserve the entire requested list. TV queries can also use station, network, or market selectors; verify IDs and coverage dates through the station catalog
• normalize toggles relative airtime % (default) vs. raw matching 15-second clip counts; optional dateres aggregation (hour/day/week/month/year). TV operators: station:, network:, market:, show:, context:
• Each series carries station (the ID the stations input takes, FOXNEWS) and stationName (GDELT's label, FOX News). If an ID can't be resolved, the series keeps stationName without station and the notice says so
• Pages points in date-then-station-name order (default 500, cap 20,000); pass nextOffset with the same inputs for the next page. The text surface's per-station count, sum, and peak cover only the returned page
• combined: true pools stations into a Combined timeline. Normalized values use pooled matching clips divided by pooled monitored clips, not an average of station percentages; no station ID is assigned to the combined series
• Smoothing accepts 0–30 timesteps and discloses leading-window loss and possible lag. Recognized upstream date resolution takes precedence over requested or inferred resolution
• Check station date ranges with gdelt_list_tv_stations before querying recent events

gdelt_get_tv_clips tool

• Up to 3,000 clips fetched per call, sorted by relevance, date descending, or date ascending; larger maxRecords values clamp to 3,000 by default
• Each clip: show name, station and stationName (resolved as in gdelt_search_tv, so a series' station passes straight into stations), air timestamp, 15-second transcript excerpt, direct Archive.org link, and optional thumbnail
• The server requests whole clock hours, so any window width works; clips outside an explicit startDatetime/endDatetime window are dropped and counted in the notice (a timespan call drops nothing)
• Returns every fetched in-window clip. At the provider ceiling, continuationWindows gives narrower windows to re-query (de-duplicate by archiveUrl); whole-hour retrieval can still prevent reaching every match in a dense hour

gdelt_get_tv_breakdown tool

• Sta