GDELT Cloud Docs — Global Event Data API & MCP

The GDELT Cloud MCP server uses bearer token authentication with API keys. This provides secure, programmatic access for AI agents, development tools, and automated workflows.

All MCP connections use bearer authentication with API keys. Generate your key from the GDELT Cloud Dashboard.

Generate API Key

Access dashboard

Navigate to GDELT Cloud Dashboard and sign in.

Navigate to API Keys

Click API Keys in the sidebar navigation.

Create new key

Click “Create New Key” and provide:

Name: Descriptive label (e.g., “Claude Desktop”, “LangChain Agent”)
Expiration (optional): Set expiration for enhanced security

Save your key

Your API key is displayed only once. Copy and store it securely.

gdelt_sk_a1b2c3d4e5f6...

You cannot retrieve the key again. If lost, you must revoke and create a new one.

API Key Format

GDELT Cloud API keys follow this format:

gdelt_sk_<64-hexadecimal-characters>

Using with MCP Clients

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "auth": {
        "type": "bearer",
        "token": "${GDELT_API_KEY}"
      }
    }
  }
}

Set environment variable:

export GDELT_API_KEY=gdelt_sk_your_key_here

Cursor IDE

Add to mcp-config.json:

{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "auth": {
        "type": "bearer",
        "token": "${GDELT_API_KEY}"
      }
    }
  }
}

Python with FastMCP

from fastmcp import Client
from fastmcp.client.auth import BearerAuth
import os

async with Client(
    "https://gdelt-cloud-mcp.fastmcp.app/mcp",
    auth=BearerAuth(token=os.environ["GDELT_API_KEY"])
) as client:
    tools = await client.get_tools()

LangChain

from langchain_mcp_adapters.client import MultiServerMCPClient
import os

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

Environment Variables

.env file
Shell profile
Docker

.env

GDELT_API_KEY=gdelt_sk_your_key_here

Load in your application:

from dotenv import load_dotenv
load_dotenv()

Add to ~/.zshrc or ~/.bashrc:

export GDELT_API_KEY=gdelt_sk_your_key_here

ENV GDELT_API_KEY=${GDELT_API_KEY}

Pass at runtime:

docker run -e GDELT_API_KEY=gdelt_sk_... myapp

Managing Keys

Revoke Keys

Open API Keys

Navigate to Dashboard → API Keys

Click Revoke

Find the key and click “Revoke”

Revocation is immediate. All applications using this key will lose access.

Key Rotation

Best practice: rotate keys every 90 days.

Create new key

Generate a new key with descriptive name.

Update applications

Update environment variables in all services. Test thoroughly before revoking old key.

Revoke old key

After confirming new key works, revoke the old one.

Next Steps

MCP Tools

Explore the Progressive Discovery wrapper and v2 GDELT Cloud catalog

Code References

CAMEO, Conflict, CAMEO+, and Goldstein interpretation

LangChain Integration

Build AI agents with GDELT Cloud MCP tools

Overview

Tools

Resources

Skills

Prompts

Integrations

Authentication

Generate API Key

API Key Format

Using with MCP Clients

Claude Desktop

Cursor IDE

Python with FastMCP

LangChain

Environment Variables

Managing Keys

Revoke Keys

Key Rotation

Next Steps

MCP Tools

Code References

LangChain Integration

​Generate API Key

​API Key Format

​Using with MCP Clients

​Claude Desktop

​Cursor IDE

​Python with FastMCP

​LangChain

​Environment Variables

​Managing Keys

​Revoke Keys

​Key Rotation

​Next Steps

MCP Tools

Code References

LangChain Integration

Generate API Key

API Key Format

Using with MCP Clients

Claude Desktop

Cursor IDE

Python with FastMCP

LangChain

Environment Variables

Managing Keys

Revoke Keys

Key Rotation

Next Steps