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

Tool	Purpose
search_articles	Search multilingual global news coverage and return structured article results
get_coverage_timeline	Track normalized media attention or raw matching article counts over time
get_tone_timeline	Track the average tone of matching coverage over time
get_source_country_timeline	Compare attention across countries where publishing outlets are based

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

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

Variable	Purpose
GDELT_DOC_API_BASE	Override the public DOC endpoint for testing
MCP_ALLOWED_ORIGINS	Comma-separated allowed browser origins
MCP_RATE_LIMIT_PER_MINUTE	MCP requests per IP per minute; defaults to 30

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