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: gdelt-events-mcp

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