Skip to main content
Glama
GDELT MCP Server

GDELT MCP Server

by MissionSquad

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 build

Configuration

The server can be configured using environment variables. Create a .env file:

cp .env.example .env

Available 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 environment

    • AND 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, HybridRel

  • startDateTime (optional): Start date in YYYYMMDDHHMMSS format

  • endDateTime (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 text

    • imageocrmeta: 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 tools
search_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

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    Each tool targets a distinct resource: articles vs. images. There is no overlap in purpose.

    Naming Consistency5/5

    Both tools follow a consistent 'search_' prefix with a noun, adhering to verb_noun naming.

    Tool Count3/5

    With only two tools, the server feels somewhat thin but remains focused. The count is borderline for its scope.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables macro/geopolitical event detection by wrapping the GDELT 2.0 API, providing tools for searching events, trending actors, and sentiment timeseries from global news.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides access to the GNews API for searching news articles and retrieving top headlines with advanced filtering options.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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