GDELT Cloud Docs — Global Event Data API & MCP

Every client below connects to the same endpoint with the same key:

https://gdelt-cloud-mcp.fastmcp.app/mcp

Create a key at gdeltcloud.com/api-keys. Your plan governs which endpoints respond, identically to REST.

Using a coding agent? Claude Code, Codex and Cursor can install the GDELT Cloud plugin instead, which wires this server, the documentation server and eight skills in one command.

Claude
Claude Code
ChatGPT
Codex
LangChain / LangGraph

Claude web and desktop. Settings → Connectors → Add custom connector, paste the server URL, and authorize with your API key.Once connected, ask normally — the model discovers the tools itself. Start broad (“what’s happening with…”) rather than naming an endpoint.

claude mcp add --transport http gdelt-cloud https://gdelt-cloud-mcp.fastmcp.app/mcp

Then set your key when prompted. Verify with /mcp inside a session — the server should list as connected.Or install the plugin, which adds the documentation server and eight skills beside it.

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

That writes ~/.codex/config.toml, where the entry looks like this — edit it there directly if you prefer:

[mcp_servers.gdelt_cloud]
url = "https://gdelt-cloud-mcp.fastmcp.app/mcp"
bearer_token_env_var = "GDELT_API_KEY"

bearer_token_env_var takes the name of an environment variable, not the key itself. A gdelt_sk_… pasted there is looked up as a variable name, matches nothing, and the request goes out unauthenticated — a 401 with nothing pointing at the cause. Codex has no ${...} interpolation, so naming the variable is the only way to hand it a secret.

Restart Codex, then verify with codex mcp list.Or install the plugin instead: it wires this server, adds the documentation server beside it, and brings eight skills.

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "gdelt_cloud": {
        "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
        "transport": "streamable_http",
        "headers": {"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    }
})
tools = await client.get_tools()

Bind tools to your agent as usual. The three discovery tools compose — see Progressive discovery.

If it does not connect

Tools do not appear

The client connected but authentication failed. Check the key is a live GDELT Cloud key (gdelt_sk_…) and has not been revoked at gdeltcloud.com/api-keys.

A call returns a plan error

Working as intended: that endpoint is not in your plan. The error names the flag it needs — see the error reference. It is deliberately not an empty result, which would be indistinguishable from missing data.

The model invents a parameter

Ask it to fetch the endpoint description first. The parameter it wants is either in the parameter reference or does not exist — the server rejects unknown filters rather than ignoring them.

MCP server

Integrations

If it does not connect

​If it does not connect

If it does not connect