Gdelt Mcp Server

cyanheads/gdelt-mcp-server

Connects Claude to the GDELT Project's DOC and TV APIs for searching and analyzing global news coverage and US television transcripts. Nine tools span article search across 65 languages and three months of coverage, time series extraction for volume and tone tracking, histogram analysis for sentiment distribution, and geographic breakdown by country or language. The TV side covers 2009 through October 2024 with clip retrieval, trending topics, contextual vocabulary analysis, and station metadata lookups. Built with shared rate limiting to respect GDELT's 1 request per 5 seconds quota. Use this when you need structured access to large scale media monitoring data or want to trace how stories propagate across languages, countries, and broadcast networks without manually polling APIs.

GitHub stars: 10
tools: 10
transport: STDIO, HTTP
env vars: 12
last updated: Nov 10, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://gdelt.caseyjhand.com/mcp --name gdelt

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http gdelt https://gdelt.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 10 tools

Verified live against the running server on Nov 6, 2026.

gdelt_search_articlesSearch the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Fetches up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL, and returns every fetched article inside the requested window. Query...6 params

Search the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Fetches up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL, and returns every fetched article inside the requested window. Query...

Parameters* required

endDatetimestring

End of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must be supplied together with startDatetime; supplying only one of the two is rejected.

maxRecordsnumber

Maximum number of articles to fetch. Defaults to 75; values above 250 run at 250 with a limitClamp disclosure unless clamping is disabled. Every fetched in-window record is returned. 250 is GDELT's...default: 75

query*string

Search query. Supports GDELT operators: phrases ("bird flu"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:TAX_DISEASE_OUTBREAK (GKG theme identifi...

sortstring

Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency).one of relevance · dateDesc · dateAsc · toneDesc · toneAsc · hybridReldefault: relevance

startDatetimestring

Start of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must be supplied together with endDatetime; supplying only one of the two is rejected.

timespanstring

Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full...

gdelt_get_coverage_timelineRetrieve 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 "volume_raw" for distinct matching-article counts per timestep and norm,...9 params

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 "volume_raw" for distinct matching-article counts per timestep and norm,...

Parameters* required

endDatetimestring

End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected. In "volume" and "tone"...

limitnumber

Maximum timesteps per page (default 10, cap 400). Larger counts clamp to 400 unless GDELT_CLAMP_LIMITS=false.default: 10

modestring

Timeline mode: "volume" returns normalized coverage % per timestep, "volume_raw" returns distinct matching-article counts (moving averages when smoothed) and the unsmoothed monitored denominator no...one of volume · volume_raw · volume_with_articles · tonedefault: volume

offsetinteger

Zero-based timestep offset — into the timeline, or into the timesteps named in points. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page.default: 0

pointsarray

Timestep dates to return alone, e.g. ["2024-01-05T12:00:00Z"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. The response then ca...

query*string

Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes), to...

smoothinginteger

Trailing moving-average width in timesteps (0–30; 0 or 1 leaves values unsmoothed). Width N needs N source steps, omitting leading steps without a full window and potentially shifting peaks later.

startDatetimestring

Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected. In "volume" and "tone"...

timespanstring

Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.

gdelt_get_tone_distributionGet 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...7 params

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...

Parameters* required

binsarray

Tone bins to return alone, e.g. [-7, 4]. Take them from histogram[].bin in a prior response, or from the list an unknown_bin error prints. The response then carries only these bins, in histogram or...

endDatetimestring

End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected. The window may predate...

limitnumber

Maximum bins per page (default 10, cap 400). Larger counts clamp to 400 unless GDELT_CLAMP_LIMITS=false.default: 10

offsetinteger

Zero-based bin offset — into the histogram, or into the bins named in bins. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page.default: 0

query*string

Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes).

startDatetimestring

Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected. The window may predate...

timespanstring

Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.

gdelt_get_coverage_breakdownBreak 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 geographicall...9 params

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 geographicall...

Parameters* required

breakdownBy*string

Breakdown dimension: "language" for source language time series, "country" for source country time series.one of language · country

endDatetimestring

limitnumber

Maximum series per page (default 10, cap 75). Larger counts clamp to 75 unless GDELT_CLAMP_LIMITS=false.default: 10

offsetinteger

Zero-based series offset — into the ranked top 10, or into the series named in series. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page.default: 0

query*string

Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes).

seriesarray

Exact series labels to return instead of the ranked overview, e.g. ["Portuguese Volume Intensity", "Vietnamese Volume Intensity"]. Take them verbatim from otherSeriesLabels or topSeries[].label in...

smoothinginteger

Trailing moving-average width in timesteps (0–30; 0 or 1 leaves values unsmoothed). Width N needs N source steps, omitting leading steps without a full window and potentially shifting peaks later.

startDatetimestring

timespanstring

Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.

gdelt_search_themesFind GDELT Global Knowledge Graph (GKG) theme identifiers for the theme: operator that gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown accept in query. Searches the identifiers in the GDELT GKG theme lookup, whi...3 params

Find GDELT Global Knowledge Graph (GKG) theme identifiers for the theme: operator that gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown accept in query. Searches the identifiers in the GDELT GKG theme lookup, whi...

Parameters* required

limitnumber

Maximum matches returned in this response. Values above 100 run at 100 with a limitClamp disclosure when clamping is enabled.default: 25

offsetinteger

Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page.default: 0

query*string

Words to find in theme identifiers (e.g. "drought", "cyber attack", "refugee"), a family prefix with a word ("wb water", "crisislex"), or a whole identifier to confirm it is listed ("TAX_DISEASE_OU...

gdelt_search_tvSearch television news closed captions for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic — 500 points by default, up to 20,000 per page. Each series carries GDELT's display name for the station and, when that...11 params

Search television news closed captions for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic — 500 points by default, up to 20,000 per page. Each series carries GDELT's display name for the station and, when that...

Parameters* required

combinedboolean

Pool selected stations into one Combined timeline. Normalized values divide pooled matching clips by pooled monitored clips; false keeps separate station series.default: false

dateresstring

Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution.one of hour · day · week · month · year

endDatetimestring

End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.

limitnumber

Maximum timeline points returned per page (default 500, cap 20,000). Larger counts clamp with limitClamp; strict deployments reject them.default: 500

normalizeboolean

When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts.default: true

offsetinteger

Zero-based point offset into the deterministic date-then-station-name ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page.default: 0

query*string

Search query for TV transcript content. Supports TV operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". Boolean OR and phrase operators also work.

smoothinginteger

Trailing moving-average width in timesteps, 0–30 (0 or 1 = none). Width N needs N source steps; leading steps cannot produce averages and peaks may appear later.

startDatetimestring

Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected.

stationsarray

Station IDs to filter to (e.g. ["CNN", "FOXNEWS", "MSNBC"]). Every supplied ID is forwarded. Alternatively use station:, network:, or quoted market: selectors in query; a selector is required. Obta...

timespanstring

Time window, e.g. "1m", "6m", "1y". Ignored when startDatetime/endDatetime are set. Check station monitoring dates with gdelt_list_tv_stations.

gdelt_get_tv_breakdownRank TV stations or shows mentioning a query. Station values are percentages of each station’s monitored airtime, or raw matching 15-second clip counts with normalize=false. Show values always represent percentages of matching clips, even with normalize=false. Labels are prese...9 params

Rank TV stations or shows mentioning a query. Station values are percentages of each station’s monitored airtime, or raw matching 15-second clip counts with normalize=false. Show values always represent percentages of matching clips, even with normalize=false. Labels are prese...

Parameters* required

breakdownBy*string

Rank stations by their airtime share or matching clip count, or shows by percentage of matching clips.one of station · show

endDatetimestring

UTC end in YYYYMMDDHHMMSS format. Must pair with an earlier startDatetime.

limitnumber

Maximum ranking rows per page (default 25, cap 10,000). Larger counts clamp with limitClamp; strict deployments reject them.default: 25

normalizeboolean

Station rankings: true returns station-airtime percentages; false returns matching 15-second clip counts. Show rankings always return matching-clip percentages.default: true

offsetinteger

Zero-based row offset after descending-value and exact-label sorting. Use nextOffset with the same query inputs for the next page.default: 0

query*string

TV transcript query. Supports phrases, Boolean OR, station:CNN, network:CBS, market:"National", show:"Bloomberg Best", and context:"vaccine".

startDatetimestring

UTC start in YYYYMMDDHHMMSS format. Must pair with a later endDatetime.

stationsarray

Station IDs to select; every supplied ID is forwarded. Alternatively select station:, network:, or quoted market: in query. A selector is required; obtain values from gdelt_list_tv_stations.

timespanstring

Relative time window, such as 1m or 6m. Ignored when both explicit datetimes are supplied. Check per-station archive coverage before selecting a window.

gdelt_get_tv_clipsRetrieve the top matching TV news clips for a query from the Internet Archive's Television News Archive: returns every fetched in-window clip, up to 3,000. Each clip includes show name, the station's display name — with its station ID when that name resolves to one — air times...7 params

Retrieve the top matching TV news clips for a query from the Internet Archive's Television News Archive: returns every fetched in-window clip, up to 3,000. Each clip includes show name, the station's display name — with its station ID when that name resolves to one — air times...

Parameters* required

endDatetimestring

End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.

maxRecordsnumber

Maximum number of clips to fetch. Defaults to 50; values above 3000 run at 3000 with a limitClamp disclosure unless clamping is disabled. Every fetched in-window record is returned. 3000 is GDELT's...default: 50

query*string

Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".

sortstring

Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first).one of relevance · dateDesc · dateAscdefault: relevance

startDatetimestring

Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected.

stationsarray

Station IDs to filter to (e.g. ["CNN", "FOXNEWS"]). Alternatively use station:, network:, or quoted market: selectors in query. A selector is required; use gdelt_list_tv_stations for station IDs, n...

timespanstring

Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV coverage varies by station; check monitoring dates with gdelt_list_tv_stations.

gdelt_get_tv_contextGet 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 with relative frequency scores (0–100, where 100 = the query term itself). Terms and scores come from GDE...7 params

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 with relative frequency scores (0–100, where 100 = the query term itself). Terms and scores come from GDE...

Parameters* required

endDatetimestring

End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.

limitnumber

Maximum score-sorted terms returned per page (default 25, cap 25,000). Larger counts clamp with limitClamp; strict deployments reject them.default: 25

offsetinteger

Zero-based term offset in descending score order. Use nextOffset with the same query inputs for the next page.default: 0

query*string

Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".

startDatetimestring

Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected. Check station monitori...

stationsarray

Station IDs to filter to (e.g. ["CNN", "FOXNEWS"]). Alternatively use station:, network:, or quoted market: selectors in query; a selector is required. Obtain IDs, network and market values, and pe...

timespanstring

Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. Check station monitoring dates with gdelt_list_tv_stations.

gdelt_list_tv_stationsList the television stations available for TV search with their market, network, monitoring start date, and monitoring end date — every station by default, or only those matching the optional stations, network, and market filters (each an exact, case-insensitive match; combine...3 params

List the television stations available for TV search with their market, network, monitoring start date, and monitoring end date — every station by default, or only those matching the optional stations, network, and market filters (each an exact, case-insensitive match; combine...

Parameters* required

marketstring

Market to narrow to (e.g. "National", "San Francisco"), matched as a whole value case-insensitively after trimming — "National" does not match "NationalSpecialty". Values come from the market field...

networkstring

Network to narrow to (e.g. "CNN", "ABC"), matched as a whole value case-insensitively after trimming — "FOX" does not match "FOXNEWS". Values come from the network field of the unfiltered list. Bla...

stationsarray

Station IDs to return (e.g. ["CNN", "FOXNEWS", "MSNBC"]) — the IDs the stations parameter of the other TV tools takes. Matches any listed ID, exactly and case-insensitively after trimming; IDs that...

Configuration

GDELT_CLAMP_LIMITSdefault: true

Clamp counts above each per-call cap; false rejects them.

GDELT_BASE_URLdefault: https://api.gdeltproject.org/api/v2

Override the base URL for the GDELT DOC and TV APIs.

GDELT_REQUEST_DELAY_MSdefault: 5300

Minimum milliseconds between GDELT requests, enforcing the 1 req/5s rate limit.

GDELT_REQUEST_TIMEOUT_MSdefault: 60000

Deadline in milliseconds for a single GDELT request; the whole call, retries included, is bounded at twice this value.

GDELT_MIRROR_PATH

SQLite file of the optional local GKG mirror the DOC tools fall back to when the DOC API refuses requests. Unset leaves it off. Built with `bun run mirror:init` from a checkout or the Docker image; on Node it needs better-sqlite3 installed.

GDELT_MIRROR_WINDOW_DAYSdefault: 7

Days of GKG slots the local mirror keeps (1-90).

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Readme

@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

View the full README on GitHub

Details

Repository: github.com/cyanheads/gdelt-mcp-server
Category: Search & Web Crawling
Package: @cyanheads/gdelt-mcp-server
Transport: STDIO, HTTP
Registry: MCP registry, active
Resources: 1
Tools verified: Nov 6, 2026

Related Search & Web Crawling MCP servers

View all

Seatableseatable/seatable-mcpMCP server for SeaTable — read, write, search, link, and query data in your bases10stars

Limpspaulbreuler/limpsMCP planning server for AI agents — plan management, full-text search, and task lifecycle10stars

Hint Services Obsidian Github Mcphint-services/obsidian-github-mcpConnect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…9stars

Eurostat Mcp Servercyanheads/eurostat-mcp-serverSearch and query the Eurostat catalogue — EU economy, demography, trade, and NUTS regional data.9stars

Microsoft Teams APImaxim-mazurok/teams-apiAI-native Microsoft Teams integration — read chats, send messages, search people9stars

Mementoscrypster/mementoPersistent memory for AI tools. Local-first knowledge graph with hybrid search.9stars

Gdelt Mcp Server

Install

Tools

Configuration

Readme

@cyanheads/gdelt-mcp-server

Details

More from cyanheads

Related Search & Web Crawling MCP servers