# 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

```bash
npm install
npm run build
```

## Configuration

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

```bash
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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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