GDELT

Explore recent global news coverage and CAMEO-coded events by place, actor, theme and tone.

Tool Reference: 11 tools with full schemas →

Use the GDELT toolkit to see what the world’s news is covering, and where. It queries a rolling window of recent data from the GDELT Project, which monitors news worldwide, in English and machine-translated from many other languages. It works at two levels:

Articles. Themes, people, organizations, places, outlets and tone that GDELT extracts from each article (its Global Knowledge Graph, or GKG).
Events. “Who did what to whom, and where”, coded by GDELT’s machine coding into the CAMEO taxonomy (protests, threats, assaults, negotiations, aid and so on), plus every article mention of each event.

The toolkit is read-only and needs no account or API key.

Example prompts

Which places in Ukraine had the most coded events yesterday? Map the top ten.

Show me the daily number of protest events in France over the past week.

What is the most-reported event in Iran this week, and which outlets covered it?

Which countries' press covered wildfires most heavily in the last few days, relative to their overall output?

Setup

There is nothing to configure. Add the GDELT toolkit to your MCP server in Toolforest and it is ready to use.

Tools

Article tools

Tool	What it does
get_status	Report the currently retained time range, data freshness, ingestion gaps and outlet-country mapping coverage. This is the authority for which dates you can query.
list_articles	List distinct article URLs that match exact metadata filters, newest first, with cursor pagination.
coverage_timeline	Count matching articles and average their tone per 15-minute, hourly or daily bucket, with per-bucket ingestion completeness.
geo_by_country	Rank mentioned countries by density: the share of all articles mentioning a country that also match your filters.
geo_by_adm1	Rank mentioned first-level regions (states, provinces) by the same density measure.
geo_by_source_country	Rank the countries outlets publish from by the same density measure. This is outlet origin, not the geography an article mentions.
geo_points	Rank mentioned places by matching article count, as compact points or a GeoJSON FeatureCollection.

Event tools

Tool	What it does
list_events	Rank CAMEO-coded events by how many qualifying article mentions they received, with actor and action geography, and article and outlet counts.
event_timeline	Count distinct events and mention rows per UTC hour or day, returning every bucket in the range.
event_geo_points	Rank the coded locations of matching events for one role: where the action took place, or where the first or second actor is.
get_event_mentions	List the articles that mentioned one event, strongest extraction confidence first, with the matching article title and outlet where available.

Queries filter on exact metadata rather than free text: GKG themes, people, organizations, places, outlets, languages and tone for articles. Your assistant maps a topic to the right codes. Event filters use exact codes: the country where the action happened (two-letter GDELT/FIPS codes, for example UP for Ukraine), actor countries (three-letter CAMEO codes, for example UKR) and CAMEO event codes (for example root code 14 for protests).

Reading the results

Every response carries metadata that says how much to trust it. Your assistant sees these notes and should pass them on.

Coverage. Each result reports whether all the underlying GDELT files for the range were ingested. For events, coverage is reported separately for all six inputs: Events, EventMentions and GKG, each in English and translated streams. An incomplete range is not evidence that nothing happened.
Confidence is not truth. GDELT scores how confidently its software extracted an event from an article. Mentions below 50 are excluded by default. A high score does not mean the event really happened as coded.
Coded geography. Event locations are where GDELT’s coding placed the actors and action. They can be wrong, and an action location is not a verified target or impact site.
Older events. Recent articles sometimes mention events first recorded before the rolling window. Those have no event record in the results, and the response says how many there were.
Counts are not unique totals. list_events returns at most 100 ranked events, and event_timeline counts an event once in every bucket in which it is mentioned.

Notes and limits

Data covers a rolling window of about the last 14 days. Use get_status to see the exact range; requests outside it are rejected rather than clipped.
Times are when GDELT observed an article (15-minute monitoring slots, UTC), not publication times.
Article location filters match a place mentioned anywhere in the article, not near a particular phrase.
Country codes are GDELT/FIPS codes, which are not always ISO codes.
Ranking tools report when results were truncated. Narrow the filters or time range to see more.
Queries share a bounded backend. If a request is refused for capacity, retry a little later or narrow it.

Attribution and credits

Data comes from the GDELT Project, which makes it openly available. Credit the GDELT Project when you publish or display results.