Skip to main content
Glama

gdelt-mcp-server

by io.github.cyanheads

Search GDELT Articles

gdelt_search_articles
Read-only

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"). 250 is a hard per-call ceiling and GDELT offers no cursor: when a query fills it, split the run into narrower startDatetime/endDatetime windows — the response hands back the exact windows to use. Note: this API covers only the most recent 3 months — use gdelt_search_tv for historical TV transcripts back to 2009.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNoSort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency).relevance
queryYesSearch query. Supports GDELT operators: phrases ("bird flu"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:DISEASE_OUTBREAK, tone<-5, near20:"flu virus", repeat3:"outbreak".
timespanNoTime 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 3-month window.
maxRecordsNoMaximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead.
endDatetimeNoEnd 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.
startDatetimeNoStart 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.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoDisclosure that the maxRecords cap was reached and more articles may exist, naming the route to them — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap.
articlesNoMatching articles sorted per the sort parameter.
timespanNoEchoed timespan parameter when provided.
totalCountNoNumber of articles returned in this response.
effectiveQueryNoEchoed query string for use in follow-up calls.
continuationWindowsNoThe queried window halved, to re-run this query against one pair at a time when maxRecords is at its 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. Absent unless the ceiling was reached with a window that is both known and wide enough to divide.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already mark this readOnly, and the description adds substantial behavioral detail beyond that: 250 is a hard per-call ceiling with no cursor, the response returns exact split windows when a query fills, timespan is ignored when startDatetime/endDatetime are set, and the API is limited to 3 months. These are exactly the kinds of runtime constraints an agent needs to call the tool correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence carries unique information: scope, return fields, query syntax, pagination limits, split strategy, and the sibling alternative. It is front-loaded with scope and return value, and the query operator list is organized and purposeful despite being somewhat long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, rich query syntax, hard pagination limit) and the presence of an output schema, the description is complete: it covers time bounds, result count, operator syntax, sort behavior implications, split strategy, and the key alternative. Nothing essential for selecting or invoking the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining the semantic implications of maxRecords (hard ceiling, not a page size, no cursor), clarifying the timespan override behavior, and detailing GDELT query operators. It also explains the pair requirement for startDatetime/endDatetime in plain operational terms.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Search the last 3 months of global news coverage using the GDELT DOC API.' It clearly states what the tool returns (up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL) and distinguishes itself from gdelt_search_tv by noting that this API covers only the recent 3 months.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance and names a concrete alternative: 'use gdelt_search_tv for historical TV transcripts back to 2009.' It also provides actionable direction for handling the 250-article ceiling by splitting queries into narrower startDatetime/endDatetime windows, so an agent knows exactly how to proceed when the limit is hit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All gdelt-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool serves a distinct purpose: search articles vs. search TV, coverage timelines vs. breakdowns vs. tone distributions, and TV-specific tools for clips, context, trending, and station listing. Even overlapping functions like get_coverage_timeline and get_tone_distribution are clearly differentiated by description.

Naming Consistency5/5

All tools follow the consistent pattern 'gdelt_<verb>_<object>' using snake_case, with verbs limited to get, search, and list. The naming is predictable and uniform, with no mixed conventions.

Tool Count5/5

Nine tools is a well-scoped number for the GDELT domain, covering both text and TV news APIs without redundancy. Each tool adds clear value, and the count is within the ideal 3-15 range.

Completeness5/5

The tool surface covers the core workflows: searching articles and TV transcripts, obtaining coverage timelines and breakdowns, analyzing tone distributions, retrieving TV clips and context, and listing stations. There are no obvious dead ends or missing operations for the stated purpose.

Resources