How do I install the gdelt mcp server?

Use a recorded configuration for your client, replace example credential values and paths, and verify the documented runtime. Restart or reconnect the client, then inspect the available tools.

What credentials does it need?

It reads `MCP_TRANSPORT_TYPE`, `MCP_LOG_LEVEL`, `GDELT_BASE_URL`, `MCP_HTTP_ENDPOINT_PATH`, `MCP_PUBLIC_URL` from the environment. Store these in your client's env block or a secrets manager — never commit them to a repository — and grant the narrowest scope that still covers your use case.

SSyncDev

Start a project

Gdelt MCP Server

Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.

Remote serverstreamable-http

What is the Gdelt MCP Server?

Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.

The short version

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

What it needs from you

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

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

Tool	What it does
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.

How to install the Gdelt MCP Server

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

Configuration as documented by the project. Restart the client after saving.

Configuration

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

Variable	Description	Required
MCP_TRANSPORT_TYPE	Configuration value read at startup.	Optional
MCP_LOG_LEVEL	Configuration value read at startup.	Optional
GDELT_BASE_URL	Endpoint or connection string the server talks to.	Yes
MCP_HTTP_ENDPOINT_PATH	Filesystem location the server is allowed to use.	Optional
MCP_PUBLIC_URL	Endpoint or connection string the server talks to.	Yes

Example prompts to try

“Use Gdelt to gdelt search articles.”
“Use Gdelt to gdelt get coverage timeline.”
“Use Gdelt to gdelt get tone distribution.”

Frequently asked questions

Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs. Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.