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

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