GDELT MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GDELT MCP Server search for articles about climate change in the past month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GDELT MCP Server
A Model Context Protocol (MCP) server that provides access to the GDELT DOC 2.0 API for searching global news articles and images.
Features
Search Articles: Search across 65 languages of global news coverage (3 months rolling window)
Search Images: Query the Visual Knowledge Graph (VGKG) for news imagery
Custom Defaults: Optimized defaults (ArtList mode, JSON format, 50 records, newest first, 1 month timespan)
Boolean Queries: Support for OR, AND operators and exact phrase matching
Flexible Timespan: Search from 1 hour to 3 months of coverage
Related MCP server: gnews-mcp-server
Installation
npm install
npm run buildConfiguration
The server can be configured using environment variables. Create a .env file:
cp .env.example .envAvailable options:
GDELT_API_TIMEOUT: API request timeout in milliseconds (default: 30000)GDELT_API_BASE_URL: GDELT API base URL (default: https://api.gdeltproject.org/api/v2/doc/doc)GDELT_DEFAULT_MAX_RECORDS: Default maximum records to return (default: 50)GDELT_DEFAULT_TIMESPAN: Default time period for searches (default: 1month)GDELT_USER_AGENT: User agent string (default: GDELT-MCP-Server/1.0)LOG_LEVEL: Logging level - debug, info, warn, error (default: info)
Usage
This MCP server is designed to be used with MCP-compatible clients. Add it to your MCP client configuration:
{
"mcpServers": {
"gdelt": {
"command": "node",
"args": ["/path/to/gdelt-mcp-server/dist/index.js"]
}
}
}Available Tools
search_articles
Search GDELT's global news database for articles.
Parameters:
query(required): Search query with support for:Exact phrases:
"climate change"OR operator:
climate OR environmentAND operator:
climate AND policy
maxRecords(optional): Number of results (1-250, default: 50)timespan(optional): Time period like "1month", "7d", "24h" (default: "1month")sort(optional): Sort order - DateDesc, DateAsc, ToneAsc, ToneDesc, HybridRelstartDateTime(optional): Start date in YYYYMMDDHHMMSS formatendDateTime(optional): End date in YYYYMMDDHHMMSS format
Example:
{
"query": "\"climate change\" OR \"global warming\"",
"maxRecords": 25,
"timespan": "7d"
}search_images
Search GDELT's Visual Knowledge Graph for news images.
Parameters:
query(required): Search term (e.g., "fire", "protest", "flood")maxRecords(optional): Number of images (1-250, default: 50)timespan(optional): Time period (default: "1month")imageType(optional):imagetag: Search by visual content (what the AI sees in the image)imagewebtag: Search by caption/context textimageocrmeta: Search by OCR text and metadata
Example:
{
"query": "wildfire",
"maxRecords": 30,
"imageType": "imagetag",
"timespan": "7d"
}API Details
This server uses the GDELT DOC 2.0 API which provides:
Rolling 3-month window of coverage (back to January 2017)
65 languages with English search terms
Deep learning-powered image analysis
Real-time and historical news data
License
MIT
Available Tools
2 toolssearch_articlesA
Search GDELT's global news database for articles across 65 languages. Supports keyword/phrase searches, Boolean operators (OR, AND), and searches back 3 months. Default returns 50 most recent articles from the past month.
Inputs: query (required), maxRecords, timespan, sort, +2 more.
search_imagesA
Search GDELT's Visual Knowledge Graph (VGKG) for news images. Can search by visual content (what's depicted), captions/context, or OCR/metadata. Searches back 3 months of global news imagery.
Inputs: query (required), maxRecords, timespan, imageType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
Each tool targets a distinct resource: articles vs. images. There is no overlap in purpose.
Both tools follow a consistent 'search_' prefix with a noun, adhering to verb_noun naming.
With only two tools, the server feels somewhat thin but remains focused. The count is borderline for its scope.
The server covers its primary domain of search (articles and images) adequately. Minor gaps like fetching specific article details are absent but not critical for a search-focused server.
Maintenance
Related MCP Connectors
Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.
Search worldwide online news in 65+ languages through the official GDELT API. No API key.
Geopolitical event detection, tone timeseries, actor trends from GDELT 2.0.
Search global news in natural language. Filter by language, country, date, sentiment, and domain.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables macro/geopolitical event detection by wrapping the GDELT 2.0 API, providing tools for searching events, trending actors, and sentiment timeseries from global news.1MIT
- FlicenseNot gradedqualityDmaintenanceProvides access to the GNews API for searching news articles and retrieving top headlines with advanced filtering options.-
- AlicenseNot gradedqualityDmaintenanceA remote, read-only MCP server for global media intelligence using GDELT DOC 2.0 API, enabling search and analysis of multilingual news coverage, tone, and attention trends.MIT
- AlicenseNot gradedqualityBmaintenanceSearch and analyze global news coverage and US television transcripts via the GDELT Project's real-time APIs via MCP.796 npm10Apache 2.0