Gdelt MCP Server

Name: Gdelt MCP Server
Author: cyanheads

by cyanheadsversion 0.8.1i★ –iComputer or cloud

Registry nameio.github.cyanheads/gdelt-mcp-server

Install

Overview

Description from the maker (original English)

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

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi3 of 3 passedChecked from public information; code not scanned yet
UsageiEarly↓ 667/wk · ★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Computer or cloud
Transport: stdio, Streamable HTTP
Category: Search & AI memory

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 3 of 3 passed
Runs on the maker’s server: what you ask it goes through their server.
Can do 10 things (tools) gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, gdelt_get_coverage_breakdown …
You fill in yourself: GDELT_CLAMP_LIMITS, GDELT_BASE_URL, GDELT_REQUEST_DELAY_MS, GDELT_REQUEST_TIMEOUT_MS, GDELT_MIRROR_PATH, GDELT_MIRROR_WINDOW_DAYS, MCP_LOG_LEVEL

You need

Runs in the cloudNothing to install; it connects over the internet
npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Works in Claude on the web, desktop and mobile:

Open Settings → Connectors
Press Add custom connector
Paste the address below and press Add
If it asks you to sign in, sign in with the maker

https://gdelt.caseyjhand.com/mcp

Or run it on your computer

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "gdelt": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/gdelt-mcp-server"
      ],
      "env": {
        "GDELT_CLAMP_LIMITS": "your-value",
        "GDELT_BASE_URL": "your-value",
        "GDELT_REQUEST_DELAY_MS": "your-value",
        "GDELT_REQUEST_TIMEOUT_MS": "your-value",
        "GDELT_MIRROR_PATH": "your-value",
        "GDELT_MIRROR_WINDOW_DAYS": "your-value",
        "MCP_LOG_LEVEL": "your-value"
      }
    }
  }
}

Run this in your terminal

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

Or run it on your computer

claude mcp add gdelt --env GDELT_CLAMP_LIMITS=your-value --env GDELT_BASE_URL=your-value --env GDELT_REQUEST_DELAY_MS=your-value --env GDELT_REQUEST_TIMEOUT_MS=your-value --env GDELT_MIRROR_PATH=your-value --env GDELT_MIRROR_WINDOW_DAYS=your-value --env MCP_LOG_LEVEL=your-value -- npx -y @cyanheads/gdelt-mcp-server

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "gdelt": {
      "url": "https://gdelt.caseyjhand.com/mcp"
    }
  }
}

Or run it on your computer

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "gdelt": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/gdelt-mcp-server"
      ],
      "env": {
        "GDELT_CLAMP_LIMITS": "your-value",
        "GDELT_BASE_URL": "your-value",
        "GDELT_REQUEST_DELAY_MS": "your-value",
        "GDELT_REQUEST_TIMEOUT_MS": "your-value",
        "GDELT_MIRROR_PATH": "your-value",
        "GDELT_MIRROR_WINDOW_DAYS": "your-value",
        "MCP_LOG_LEVEL": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "gdelt": {
      "type": "http",
      "url": "https://gdelt.caseyjhand.com/mcp"
    }
  }
}

Or run it on your computer

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "gdelt": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/gdelt-mcp-server"
      ],
      "env": {
        "GDELT_CLAMP_LIMITS": "your-value",
        "GDELT_BASE_URL": "your-value",
        "GDELT_REQUEST_DELAY_MS": "your-value",
        "GDELT_REQUEST_TIMEOUT_MS": "your-value",
        "GDELT_MIRROR_PATH": "your-value",
        "GDELT_MIRROR_WINDOW_DAYS": "your-value",
        "MCP_LOG_LEVEL": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

ChatGPT connects only to servers on the internet:

Open ChatGPT on the web → Settings → Connectors (Apps)
Press Create or Add (some plans need Developer mode under Advanced first)
Paste the address below, give it a name and save
If it asks you to sign in, sign in with the maker

https://gdelt.caseyjhand.com/mcp

Menu names can differ slightly by plan and over time.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

GDELT_CLAMP_LIMITS env
Clamp counts above each per-call cap; false rejects them.
GDELT_BASE_URL env
Override the base URL for the GDELT DOC and TV APIs.
GDELT_REQUEST_DELAY_MS env
Minimum milliseconds between GDELT requests, enforcing the 1 req/5s rate limit.
GDELT_REQUEST_TIMEOUT_MS env
Deadline in milliseconds for a single GDELT request; the whole call, retries included, is bounded at twice this value.
GDELT_MIRROR_PATH env
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; o…
GDELT_MIRROR_WINDOW_DAYS env
Days of GKG slots the local mirror keeps (1-90).
MCP_LOG_LEVEL env
Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Tool names and descriptions exactly as the server reported them on Nov 6, 2026. The maker wrote them, not us; we show them as plain text.

gdelt_search_articles
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 sup
gdelt_get_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 "volume_raw" for distinct matching-article counts per timestep and norm, th
gdelt_get_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 clu
gdelt_get_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 o
gdelt_search_themes
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, which
gdelt_search_tv
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 nam
gdelt_get_tv_breakdown
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 preserve
gdelt_get_tv_clips
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 timestam
gdelt_get_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 with relative frequency scores (0–100, where 100 = the query term itself). Terms and scores come from GDELT'
gdelt_list_tv_stations
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; combined w

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 8, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account cyanheads, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
✓ Pass
Endpoint responds
Responded in 79 ms (HTTP 200)
– Not applicable
Sign-in with OAuth
No sign-in needed
✓ Pass
No hidden instructions in tool descriptions
Read 10 tool descriptions and found no hidden instructions to the AI

Compared with others in Search & AI memoryi

More stars than 0% of the other 5716 servers in this category
Published to the registry more recently than 84% of the other 5716 servers in this category
Basic checks equal to or better than 100% of the other 5716 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Gdelt MCP Server safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

Either way works: install it on your computer or connect to the cloud version.

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.8.1) reached the registry 7 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. It connects by URL, so apps that accept remote MCP servers work too, such as ChatGPT in developer mode.

What can I use instead?

In the same category: Context7, Codebase Memory, Exa

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Context7

Feeds AI the latest docs for libraries and frameworks before it answers, so code it writes does not use outdated, removed functions.

by upstashWidely used↓ 972.7K/wk★ 64.2KUpdated 2 days ago

Computer or cloud

Install

Codebase Memory

Codebase knowledge graph for AI agents — 162 languages, sub-ms queries, 99% fewer tokens.

by DeusDataWidely used↓ 18K/wk★ 48.1KUpdated 22 days ago

Runs on your computer

Install

Exa

Connect AI agents to Exa for web search, content fetching, and multi-step research.

by exa-labsWidely used★ 5.2KUpdated 2 months ago

Runs in the cloud✓ exa.ai

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

@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

Tool	Description
`gdelt_search_articles`	Search recent global news with full-text and filter operators. Returns every fetched in-window article, up to 250 per call, with date-window continuation guidance at the provider ceiling.
`gdelt_get_coverage_timeline`	Track normalized coverage, raw matching-article counts with monitored denominators, or average tone. Expand supplied article references for selected timesteps.
`gdelt_get_tone_distribution`	Get a tone histogram (bins ~−30 to +30) showing whether coverage is uniformly negative, bimodal, or clustered near neutral.
`gdelt_get_coverage_breakdown`	Compare coverage by source language or source country. Values are normalized shares of each source population's media output, not additive article counts.
`gdelt_search_themes`	Find GKG theme identifiers for the `theme:` operator the DOC tools accept — `drought` finds `NATURAL_DISASTER_DROUGHT`, `cyberattack` finds `CYBER_ATTACK` — ranked by the count GDELT's theme lookup lists.
`gdelt_search_tv`	Search television news closed captions and return separate station timelines or pooled coverage.
`gdelt_get_tv_breakdown`	Rank stations by airtime share or matching-clip count, and shows by share of matching clips.
`gdelt_get_tv_clips`	Retrieve up to 3,000 matching TV clips with transcript excerpts and Internet Archive viewing links, returning every fetched in-window clip.
`gdelt_get_tv_context`	Get the most frequent co-occurring words and phrases from GDELT's relevance-ranked sample of TV clips matching a query.
`gdelt_list_tv_stations`	List TV stations with market, network, and monitoring date ranges — all of them, or filtered by station ID, network, or market — to verify station availability before querying.

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

Only the beginning is shown; read the rest in the repo

Gdelt MCP Server

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Or run it on your computer

Or run it on your computer

Or run it on your computer

Or run it on your computer

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Search & AI memoryi

Common questions

Alternatives

Context7

Codebase Memory

Exa

README from the maker

Overview

Tools

Capability reference

gdelt_search_articles tool

gdelt_get_coverage_timeline tool

gdelt_get_tone_distribution tool

gdelt_get_coverage_breakdown tool

gdelt_search_themes tool

gdelt_search_tv tool

gdelt_get_tv_clips tool

gdelt_get_tv_breakdown tool

`gdelt_search_articles` tool

`gdelt_get_coverage_timeline` tool

`gdelt_get_tone_distribution` tool

`gdelt_get_coverage_breakdown` tool

`gdelt_search_themes` tool

`gdelt_search_tv` tool

`gdelt_get_tv_clips` tool

`gdelt_get_tv_breakdown` tool