GDELT MCP

A remote, read-only Model Context Protocol server for global media intelligence using the public GDELT DOC 2.0 API.

The server requires no GDELT API key and is deployed on Vercel.

Tools

The documented GDELT GEO API currently returns HTTP 404, so geographic mapping is deliberately not exposed as a tool.

Related MCP server: gnews-mcp-server

Important interpretation note

GDELT is a large-scale automated media-monitoring system. Its translation and tone analysis can contain errors. Results should be interpreted as signals about news coverage, not as verified facts or direct measurements of real-world events.

Reliability controls

GDELT currently asks API users to keep requests at least five seconds apart. This server therefore:

• serializes outbound GDELT requests at least 5.5 seconds apart per warm instance;

• limits each upstream attempt to 15 seconds;

• retries HTTP 429 once after at least six seconds;

• respects a longer Retry-After header when supplied;

• caches successful identical requests for five minutes; and

• limits response size and MCP request volume.

Because Vercel uses shared serverless egress, GDELT may still occasionally return HTTP 429 during periods of heavy traffic. The MCP returns that error transparently instead of fabricating data.

Architecture

• Plain Node.js with no runtime dependencies

• Vercel serverless functions in the Dubai region

• Stateless MCP Streamable HTTP

• Primary MCP endpoint: /mcp

• Alternate MCP endpoint: /api/mcp

• Health endpoint: /health

• Optional deep DOC check: /health?deep=1

Local validation

npm install
npm test
npm run build

Local development with Vercel CLI

npm install -g vercel
vercel dev

Then connect an MCP client to:

http://localhost:3000/mcp

Deploy to Vercel

1. Import this repository into Vercel.

2. No environment variables are required.

3. Deploy and open /health.

4. Connect the MCP client to https://<your-domain>/mcp.

Optional environment variables

No secrets should be committed.

Example prompts

• “Search global coverage of sovereign AI published in the last 24 hours.”

• “Compare how much attention different publishing countries are giving to data-centre power constraints.”

• “Show the seven-day coverage-volume and tone trends for NVIDIA export restrictions.”

• “Find the latest Arabic-language coverage of AI regulation.”

GDELT query examples

The query field supports GDELT syntax, including:

"artificial intelligence"
(climate OR flooding OR drought)
near20:"Trump Putin"
theme:ECON_INFLATION
tone<-5

Structured tool arguments can also add source-country, language, exact-domain, theme and tone filters.

MCP client configuration

{
  "mcpServers": {
    "gdelt": {
      "url": "https://<your-domain>/mcp"
    }
  }
}

License

MIT