GDELT Cloud MCP Server

What is GDELT Cloud MCP Server?

GDELT Cloud MCP Server is the hosted MCP endpoint for GDELT Cloud, letting Claude, ChatGPT, Codex and custom agents query structured geopolitical events, clustered news stories and linked people, organizations and places with the same data as the GDELT Cloud REST API.

GDELT Cloud turns the public GDELT article stream into a structured database. Events are coded under its own taxonomy (CAMEO+ and Conflict categories) with actors, geography, source evidence and metrics; Stories cluster the articles behind them; entities connect coverage to the people and organizations involved. It also ingests open registries onto the same entity spine, including SEC filings, GLEIF, USAspending, FRED, Global Energy Monitor and Epoch AI. The docs describe the MCP server as routing to the same serve functions as the API, so an answer through MCP is one you could have got with curl.

How to use GDELT Cloud MCP Server?

You need a GDELT Cloud account. The server URL is:

https://mcp.gdeltcloud.com/mcp

It uses Streamable HTTP. Claude and ChatGPT sign in with OAuth in the browser; clients that use bearer authentication take an API key (prefixed gdelt_sk_) created at gdeltcloud.com/api-keys. Your plan governs which endpoints respond, exactly as with REST.

Claude Code

claude mcp add --transport http gdelt-cloud https://mcp.gdeltcloud.com/mcp

Then open /mcp inside a session and follow the OAuth sign-in flow. GDELT Cloud also offers a plugin for Claude Code, Codex and Cursor (gdelt-cloud/plugins on GitHub) that adds this server, a documentation server and eight skills.

Claude Desktop and claude.ai

Go to Settings → Connectors → Add custom connector, paste the server URL, sign in with your GDELT Cloud account and approve the connection. No API key is needed.

Cursor

Add the server to ~/.cursor/mcp.json and authenticate from Cursor's MCP settings:

{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://mcp.gdeltcloud.com/mcp"
    }
  }
}

VS Code

Add it to .vscode/mcp.json; VS Code starts the OAuth sign-in when the server first runs:

{
  "servers": {
    "gdelt-cloud": {
      "type": "http",
      "url": "https://mcp.gdeltcloud.com/mcp"
    }
  }
}

Codex (API key)

GDELT Cloud documents Codex with a bearer key read from an environment variable:

export GDELT_API_KEY=gdelt_sk_...
codex mcp add gdelt-cloud \
  --url https://mcp.gdeltcloud.com/mcp \
  --bearer-token-env-var GDELT_API_KEY

bearer_token_env_var takes the name of the variable, not the key itself.

Key features of GDELT Cloud MCP Server

• Official remote server, same data and entitlements as the GDELT Cloud REST API v2.
• 116 named domain operations with typed arguments, according to the docs, across news, identity, countries, Situations, Monitors and specialist datasets (media tone, facilities, filings, GLEIF, energy, AI compute, macro, risk screening, maritime AIS).
• Entity resolution first: unified_entity_search resolves a name to candidate IDs, search_entities discovers who appears in reporting over a date range or place.
• Free, unmetered discovery helpers: get_data_catalog, get_parameter_options and get_event_taxonomy.
• Monitors: preview a standing question, then save it to run on a schedule with email or signed-webhook delivery; writes such as create_monitor and update_monitor require host approval.
• response_mode="compact" (default) or "full", with record links, evidence and coverage kept explicit so agents can cite sources.
• Entitlement errors name the plan flag required, instead of returning an empty result that looks like missing data.

Use cases of GDELT Cloud MCP Server

• Country briefings: "What changed in Nigeria over the last 7 days? Group events by category and cite the stories."
• Entity investigations: resolve a company, then follow its linked events, stories, press tone, SEC filings and facilities.
• Ongoing situations: follow a Situation that collects the stories and coded events about one developing occurrence.
• Alerts: "Set up a Monitor for protests near ports in this region and send matches to my webhook." Preview first, then confirm.
• Supply-chain and asset research: search power plants, mines, ports and data centers, with ownership and source observations.

Troubleshooting GDELT Cloud MCP Server

• Tools do not appear: the client connected but authentication failed. Check the key is a live gdelt_sk_ key that has not been revoked at gdeltcloud.com/api-keys, or redo the OAuth sign-in.
• A call returns a plan error: that endpoint is not in your plan. The error names the flag it needs.
• The model invents a parameter: ask it to fetch the endpoint description first; the server rejects unknown filters rather than ignoring them.
• Codex gets a 401: bearer_token_env_var was set to the key itself instead of the variable name.
• Old tools or endpoint: if a client still stores an older endpoint, update it to https://mcp.gdeltcloud.com/mcp, sign in again and refresh the tool catalog.