mcp-gdelt

MissionSquad/mcp-gdelt

3.2

If you are the rightful owner of mcp-gdelt and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The GDELT MCP Server provides access to the GDELT DOC 2.0 API for searching global news articles and images.

Tools
2
Resources
0
Prompts
0

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