gdelt-mcp

A small MCP server that gives AI assistants reliable access to the GDELT DOC 2.0 API (worldwide online news, 65 languages, rolling 3-month window).

GDELT accepts one request every 5 seconds per IP address. Cloud fetchers and AI tools share their outgoing IP addresses with many other users, so their GDELT calls are often refused with HTTP 429 before they even start. gdelt-mcp runs on a machine with its own address and acts as a polite proxy:

• one queue for all calls: one GDELT request at a time, at least 6 s apart (configurable, never under 5 s);

• retries after a 429 with a global back-off (10 s, then 20 s), and a clear error when GDELT stays unavailable;

• cache: 10 minutes for recent windows, 24 hours for windows that ended more than 3 hours ago; identical concurrent calls are merged; a copy up to 2 hours old is served, flagged stale, if GDELT keeps failing;

• compact, exact results: tables (columns + rows) instead of pages that a model has to summarise;

• safe inputs: explicit UTC windows, dates without a timezone are refused, country names and ISO codes mapped to GDELT's names (GDELT's 2-letter codes are FIPS codes: CH is China, not Switzerland).

French installation guide: docs/guide-fr.md.

Tools

Common parameters of the GDELT tools:

• query — GDELT syntax: keywords, "exact phrase", (a OR b), -excluded. GDELT machine-translates non-English coverage, so English keywords also match articles in other languages.

• source_country — outlets based in a country: English or French name (Germany, Royaume-Uni) or ISO 3166 code (DE).

• source_lang — original language: name or ISO code (spanish, es).

• domain, domain_exact — a single outlet (domain: includes subdomains, domain_exact uses domainis:).

• start / end (ISO 8601 with timezone, within the last 3 months) or timespan (36h, 3d, 1w); default: the last 24 hours. gdelt_topic_summary takes start_date / end_date (whole UTC days, YYYY-MM-DD) instead.

• max_articles (gdelt_topic_summary only, 250 to 2000, default 1000) — how far back the article list is read, in pages of 250, one GDELT request (~6 s) per page. When the period holds more articles than this, articles_listed.complete is false, top_countries and top_languages count the newest max_articles only (stopped_by: "max_articles"), and the number of countries comes from the source-country timeline instead of the list.

seen is the time GDELT first saw an article (UTC). It is usually close to the publication time but is not the publication time. GDELT only provides titles and metadata: open the URL to read an article.

Example result of gdelt_search_articles (shortened):

{
  "query": "(Brazil OR Brazilian) election sourcecountry:germany",
  "window": { "start": "2026-09-19T06:00:00Z", "end": "2026-09-22T06:00:00Z" },
  "sort": "date_desc",
  "count": 75,
  "max_records": 75,
  "truncated": true,
  "next_end": "2026-09-20T17:45:00Z",
  "columns": ["seen", "domain", "lang", "country", "title", "url"],
  "rows": [["2026-09-22T05:30:00Z", "example.de", "German", "Germany", "…", "https://…"]],
  "source": { "cached": false, "stale": false, "fetched_at": "2026-09-22T06:00:04Z", "gdelt_url": "https://api.gdeltproject.org/…" }
}

Errors come back as tool errors with a code: invalid_input, gdelt_query_error (GDELT's own message, e.g. a missing parenthesis), gdelt_rate_limited, gdelt_unavailable, proxy_busy (with retry_after_s).

Related MCP server: AllNewsAPI MCP

Deploy on a server (Ubuntu 22.04 / 24.04)

You need a server with its own public IPv4 address, a host name whose A record points to it (a subdomain of your domain, or a free name such as DuckDNS), and ports 80 and 443 open in the provider's firewall (many cloud providers open only SSH on a new server).

curl -fsSLO https://raw.githubusercontent.com/nadirdev1/gdelt-mcp/main/deploy/install.sh
sudo bash install.sh mcp.example.org

The script installs Docker if needed, then picks a mode (MODE=standalone or MODE=proxy forces one):

• standalone, when ports 80/443 are free: Caddy runs next to the app and gets the HTTPS certificate itself;

• proxy, when a web server already uses 80/443: the app listens on 127.0.0.1 only. For nginx or Apache, the script offers to add a site for the host name (a new file; nothing else is touched) and to get its certificate with certbot; for other servers (hosting panels, Traefik, Caddy on the host) it prints what to add.

It then generates the access key and prints how to connect:

URL:           https://mcp.example.org/mcp
Header name:   X-API-Key
Header value:  <key>

Add it as a custom connector in your MCP client. In Claude: Settings → Connectors → Add custom connector, with the URL above (choose "Continue anyway" if Claude cannot verify the server: it refuses every request without the key), authentication set to none, and a request header X-API-Key whose value is the key; Claude stores header values encrypted and never shows them again. Authorization: Bearer <key> works too. The key is the secret: anyone who has it can use your GDELT quota.

For clients that cannot send headers, run the installer with ALLOW_TOKEN_IN_URL=true: the key is then also accepted in the URL, https://mcp.example.org/mcp/<key>, which becomes a secret that shows up on screens and in logs. The web server must then not log request paths for this host (the script's nginx and Apache sites disable access logs; Caddy logs nothing by default).

Useful commands on the server:

cd /opt/gdelt-mcp
sudo docker compose ps                           # status
sudo docker compose logs -f app                  # logs (one JSON line per GDELT request)
sudo grep MCP_TOKEN .env                         # show the key

Updating

The server never updates itself. To deploy a version, run on the server:

sudo bash /opt/gdelt-mcp/deploy/update.sh            # latest commit of main
sudo bash /opt/gdelt-mcp/deploy/update.sh v0.3.2     # a tag or a commit

The script shows the running and the target commits, asks for confirmation, fetches the code, rebuilds the image, restarts the app, checks /health and records the deployed commit in /var/lib/gdelt-mcp/deployed. The tests run on GitHub Actions for every push: check that they are green before deploying.

For a private repository, give the server a read-only deploy key once; both settings are kept in .env:

sudo ssh-keygen -t ed25519 -N '' -f /root/.ssh/gdelt-mcp-deploy    # add the .pub as a read-only deploy key on GitHub
sudo REPO_URL=git@github.com:owner/gdelt-mcp.git DEPLOY_KEY=/root/.ssh/gdelt-mcp-deploy bash /opt/gdelt-mcp/deploy/update.sh

Servers installed before 0.3.2 had a systemd timer that deployed main on its own every 30 minutes; install.sh removes it when run again, and docs/guide-fr.md (section 5) gives the manual steps.

Configuration

Environment variables (set in /opt/gdelt-mcp/.env, then sudo docker compose up -d):

Local development

npm ci
npm test                     # unit tests + end-to-end tests against a mock GDELT, with MCP clients of both protocol eras
npm run build
ALLOW_NO_TOKEN=true PORT=3000 node dist/index.js   # MCP endpoint: http://localhost:3000/mcp

Built with the MCP TypeScript SDK v2: stateless Streamable HTTP, serving both 2026-07-28 clients and 2025-era clients (initialize handshake).

Data and credits

All data comes from The GDELT Project, an open platform whose datasets may be used freely provided GDELT is cited as the source. This proxy respects GDELT's published rate limit; for heavy use, GDELT recommends its bulk datasets instead of the API.

License

MIT