@cyanheads/gdelt-mcp-server

v0.2.5

Published

9 hours ago

Search and analyze global news coverage and US television transcripts via the GDELT Project's real-time APIs via MCP. STDIO or Streamable HTTP.

Public Hosted Server: https://gdelt.caseyjhand.com/mcp

Tools

Nine tools across two GDELT APIs — DOC API for global print/web news (last 3 months, 65 languages, no auth) and TV API for US television transcripts (2009–Oct 2024, 150+ stations):

| Tool | Description | |:---|:---| | gdelt_search_articles | Search the last 3 months of global news coverage (65 languages) with full-text and filter operators. Returns up to 250 articles, and hands back the date windows to re-query when that ceiling is hit. | | gdelt_get_coverage_timeline | Retrieve a time series of coverage volume or average tone for a query. volume_with_articles mode includes top articles per spike timestep, with points to render a timestep's full article list. | | gdelt_get_tone_distribution | Get a tone histogram (bins ~−30 to +30) showing whether coverage is uniformly negative, bimodal, or clustered near neutral. | | gdelt_get_coverage_breakdown | Break down coverage volume by source language or source country — a multi-series time series showing geographic propagation. Values are normalized shares of media output, not article counts. | | gdelt_search_tv | Search US television news closed captions (2009–Oct 2024) and return per-station airtime time series. | | gdelt_get_tv_clips | Retrieve up to 3,000 matching TV clips with transcript excerpts and Internet Archive viewing links, and the date windows to re-query when that ceiling is hit. | | gdelt_get_tv_context | Get the most frequent co-occurring words and phrases from TV clips matching a query. | | gdelt_get_tv_trending | Retrieve trending topics currently dominating US television news (updated every 15 minutes; no query required). | | gdelt_list_tv_stations | List all TV stations with market, network, and monitoring date ranges to verify station availability before querying. |

`gdelt_search_articles`

Search the last 3 months of global news with GDELT's full query syntax.

Keywords, phrases ("bird flu"), boolean OR, and exclusion (-sports)
Filter operators: sourcecountry:, sourcelang:, domain:, theme: (GKG taxonomy), tone</tone>
Proximity and repetition: near20:"flu virus", repeat3:"outbreak"
Configurable sort (relevance, date) and result count (up to 250)
Returns URL, title, publication date, domain, language, source country, and social image URL
250 is a hard per-call ceiling, not a page size — GDELT exposes no cursor. Fill it and the response returns continuationWindows: the queried window halved, ready to re-query. The halves overlap by a second so nothing falls through the seam; de-duplicate by url
Query is echoed in response for chaining

`gdelt_get_coverage_timeline`

Retrieve when coverage of a topic spiked, with three modes:

volume — normalized percentage of all global coverage per timestep
volume_with_articles — volume plus top articles driving each spike; use for signal detection without a follow-up search call
tone — average sentiment score per timestep (combine with gdelt_get_tone_distribution for the full picture)
Every article reference is always in structuredContent; the text surface renders the first 3 links per timestep beside that timestep's true count, and points: ["<date>"] renders named timesteps in full
Configurable smoothing and time range

`gdelt_get_tone_distribution`

Snapshot tone histogram across all articles matching a query.

Bins from approximately −30 to +30; each bin includes representative article URLs
Summary fields: peakNegativeBin, peakPositiveBin, neutralPct (% of articles in the −2 to +2 range)
Distinct from the tone timeline — distribution across all matching articles, not over time

`gdelt_get_coverage_breakdown`

Multi-series time series showing which countries or languages drove coverage.

Break down by language or country
Top 10 series by total volume; remaining series aggregated into an "Other" bucket and named in otherSeriesLabels
Nothing is dissolved into "Other" anonymously — pass any label to series: ["<label>"] and that series comes back complete under selectedSeries, alongside the usual overview
Values are normalized — the topic's share of media output, not absolute article counts. Small media markets with concentrated coverage rank above large markets with diverse output, so a high value means the topic dominated that source's coverage rather than that it published the most articles
Use to trace how a story propagated geographically

`gdelt_search_tv`

Search US television news transcripts (2009–Oct 2024) with per-station airtime analysis.

Structured stations parameter (e.g. ["CNN", "FOXNEWS"]) — the server embeds station filters in the query string
Normalize results to relative % or return raw counts
TV-specific operators: market:, show:, context:
Use gdelt_list_tv_stations to verify station active date ranges before querying recent events

`gdelt_get_tv_clips`

Retrieve actual TV news clips driving a coverage signal.

Up to 3,000 clips per call
Each clip: show name, station, air timestamp, 15-second transcript excerpt, direct Archive.org link, and optional thumbnail
3,000 is a hard per-call ceiling, not a page size — GDELT exposes no cursor. Fill it and the response returns continuationWindows: the queried window halved, ready to re-query. The halves overlap by a second so nothing falls through the seam; de-duplicate by archiveUrl
Sort by relevance, date descending, or date ascending

`gdelt_get_tv_context`

Vocabulary framing analysis for TV coverage of a topic.

Returns the most frequent non-stopword terms from matching clips
Relative frequency scores (query term = 100)
Use to identify narrative framing, related concepts, or follow-up search terms

`gdelt_get_tv_trending`

Zero-argument entry point for the current TV news cycle.

Returns trending topics, keywords, and phrases dominating national networks
Updated every 15 minutes
Note: coverage data ends Oct 2024; results reflect the archive endpoint, not a live feed

`gdelt_list_tv_stations`

Station metadata lookup before querying.

All available stations with market, network, monitoring start date, and end date
isActive flag — true when end date is within the last 24 hours
Use to verify a station was active during a target time period

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling — handlers throw, framework catches, classifies, and formats
Pluggable auth: none, jwt, oauth
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
STDIO and Streamable HTTP transports

GDELT-specific:

Shared rate-limit queue (1 req/5s) across all tools — enforces GDELT's published limit without caller coordination
Two service layers (GdeltDocService, GdeltTvService) mapping clean tool parameters to the DOC and TV API URL conventions
TV station filter operators embedded in query strings internally — callers pass structured stations arrays, not raw query syntax

Agent-friendly output:

Query echo on every response — searches return the original query and applied timespan so agents can chain calls without re-deriving parameters
Discriminated series labels — timeline and breakdown responses carry typed label fields ("Volume Intensity", "Average Tone", language/country names) rather than positional arrays
Structured station metadata — isActive boolean and ISO 8601 date fields let agents reason about TV station availability without parsing date strings
Partial-coverage signals in distribution output — neutralPct, peakNegativeBin, peakPositiveBin summary fields let agents branch on sentiment without histogramming the raw bins themselves

Getting started

Public Hosted Instance

A public instance is available at https://gdelt.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "streamable-http",
      "url": "https://gdelt.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gdelt-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gdelt-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "gdelt-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/gdelt-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node.js v24+).
No API key required — GDELT is a free public API.

Installation

Clone the repository:

git clone https://github.com/cyanheads/gdelt-mcp-server.git

Navigate into the directory:

cd gdelt-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env if you need to override defaults

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

| Variable | Description | Default | |:---------|:------------|:--------| | GDELT_BASE_URL | Override the GDELT API base URL for both DOC and TV APIs. | https://api.gdeltproject.org/api/v2 | | GDELT_REQUEST_DELAY_MS | Minimum milliseconds between GDELT requests (enforces 1 req/5s limit). | 5100 | | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_HTTP_PORT | Port for the HTTP server. | 3010 | | MCP_HTTP_ENDPOINT_PATH | HTTP endpoint path where the MCP server is mounted. | /mcp | | MCP_PUBLIC_URL | Public origin override for TLS-terminating reverse-proxy deployments. | none | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_LOG_LEVEL | Log level (debug, info, warning, error, etc.). | info | | MCP_GC_PRESSURE_INTERVAL_MS | Opt-in Bun-only forced-GC pressure loop in ms. Try 60000 if heap growth is observed under sustained HTTP load. | 0 (disabled) | | LOGS_DIR | Directory for log files (Node.js only). | <project-root>/logs | | STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1. | in-memory | | OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security audit
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t gdelt-mcp-server .
docker run --rm -p 3010:3010 gdelt-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/gdelt-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

| Directory | Purpose | |:----------|:--------| | src/index.ts | createApp() entry point — registers tools and inits services. | | src/config | Server-specific environment variable parsing and validation with Zod. | | src/mcp-server/tools | Tool definitions (*.tool.ts). Nine tools across DOC and TV APIs. | | src/services/gdelt-doc | GdeltDocService — wraps the DOC API for article search, timelines, tone, and breakdowns. | | src/services/gdelt-tv | GdeltTvService — wraps the TV API for transcript search, clips, context, and trending. | | src/services/gdelt-rate-limiter | GdeltRateLimiter singleton — shared 1 req/5s queue across both services. | | tests/ | Unit and integration tests mirroring src/. |

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools via the barrels in src/mcp-server/tools/definitions/index.ts
Wrap GDELT API calls: validate raw JSON → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme