Skip to main content
The MCP server exposes GDELT Cloud to any model that speaks the Model Context Protocol. It is the same data and the same entitlements as the REST API — the server routes to the same serve functions, so an answer you get through MCP is one you could have got with curl.
Sign in with OAuth in ChatGPT or Claude, or use a GDELT Cloud API key in a compatible client. Per-client setup is in Integrations. This is the canonical public connection. Existing Horizon connections remain available during migration; reconnect explicitly to use the current named tools. OAuth consent is specific to each connection. The MCP server remains available for your own agent workflows, including native FRED/ALFRED macro series and company filings. The separate hosted Agent UI and Monitoring Brief generation are temporarily unavailable. The retired Alpha Vantage proxy is no longer offered; see External tools for the supported alternatives and their limits.

Walk through a real question

Connect, ask broadly, drill down, check the citations — one question end to end.

How the tools are organised

The current public server exposes named operations with direct typed arguments. Use connected tool descriptors for the current public release. Familiar operations can be called directly; client-native tool search or deferred loading controls schema access where supported. Start from the user’s intent and the smallest useful workflow. Use the core tools for Events, Stories, identities, countries, Situations and Monitors. Resolve a name with unified_entity_search; use search_entities to discover actors in reporting over date, geography, taxonomy and co-occurrence filters. These operations share entity IDs but answer different questions. Use facilities for physical sites, then specialists for native evidence. Optional get_data_catalog orients to domains and relationships. For core sections, use get_data_catalog(domain="gdelt_cloud", section="identity"); omit section for the whole core catalog. get_parameter_options supplies unfamiliar categorical choices, while scoped get_event_taxonomy explains Event categories and subcategories. Reuse a known schema rather than requiring discovery before every call. Keep the default taxonomy page size and paginate only when needed. Authorized mutations use named tools such as create_monitor and update_monitor, with host approval. Preview never saves or sends delivery. The explicit legacy wrapper compatibility profile retains domain list/get/call tools and gdelt_cloud_tool_write; it is not the default public surface.

Every category and every tool

The full surface, generated from the same declaration the docs and the API reference share.

Results in chat and in code

Data operations accept response_mode="compact" (default) or "full". Compact keeps record identifiers, returned links, selected imagery, evidence, filters and coverage. A compact list page requests only the records it shows (8 Event, Story or entity cards, 60 other records), so next_cursor continues after the last record shown; _mcp_projection reports requested_limit and applied_limit when it asked for fewer. Full returns larger pages. Registry coverage keeps publication and completeness decisions, every source identity and its limits, and exact served/missing dates. Repeated build and adjudication audit reports are omitted with an omitted_registry_audit_reports count. Full preserves the bounded API response, including those audit reports. Neither mode fetches extra pages. Use returned GDELT Cloud Event, Story, Situation, entity and facility links for product records. Original publisher links support underlying reporting; registry facts retain their dataset attribution. A missing image or link is not a reason to invent one. Partial coverage is not a zero result. Research results belong in native chat: linked titles, selected returned images, compact comparison tables and client-native charts where supported. Rank and compare Events by significance, which scores both families on one scale. Describe a CAMEO+ Event with its category/subcategory and the four core metrics (magnitude is category-relative; the other three scores are not forecast probabilities); a Conflict Event has no sub-factor metrics. Font, color, icons and image size are controlled by the client. Missing images leave a complete text answer. Maps, when supported by the client, must use returned coordinates and precision rather than place/business listings. App blocks are reserved for account navigation and Monitor workflows. gdelt_cloud_monitor_form opens an editable setup form using the parameters discovered for preview_monitor. It previews the actual scope through the same authenticated API; it never saves or sends by itself. Ordinary preview_monitor calls remain native chat. Only account help and the editable Monitor form use app components; exact rendering depends on the client. To propose a Monitor, preview the actual scope, review the matches and coverage, then confirm saving paused or starting scheduled checks. Delivery can use email, webhook, or both, subject to the API’s validation and plan access. Preview sends no notification and creates no Monitor. Website signup and sign-in happen during the OAuth/account journey. Account help provides sign-in and connection documentation; the MCP does not promote subscriptions or initiate purchases. Connecting supplies a concise overview of every data group, record types, Event taxonomy and metrics. For deeper relationships and analytical guidance, read the free resource gdelt://guides/connection-orientation or request gdelt_research_system_prompt. Both return the same detailed guide. Exact schemas and specialist workflows remain available on demand; a simple lookup does not require loading the whole guide.

Guidance on demand

Initialization instructions establish intent, structured-data selection and evidence handling. The compatible research prompt points to shared skills and resources instead of repeating a long manual. Ask a concrete question; your agent should discover the relevant schema and workflow, then ask a focused follow-up only when it changes the scope or next action.

Facilities and minerals

Find U.S. mineral facilities, inspect GEM overlap, read country reserves and follow participant identities through REST and MCP.

What is metered

Data operations use the same usage admission as the REST API. Local get_data_catalog, get_parameter_options and get_event_taxonomy discovery is not metered. An endpoint your entitlement does not include returns an error naming what it needs — never an empty result, which would be indistinguishable from missing data.

Beyond GDELT Cloud data

Web research is optional support for a GDELT Cloud task: initial orientation, corroboration, or reading a relevant source page. It must not replace missing structured evidence or serve as a standalone web-search proxy. Prediction-market tools have been retired. See Supporting research for the supported web operations.

Integrations

Claude, Claude Code, ChatGPT, Codex, LangChain.

Plugins

Claude Code, Codex and Cursor: both servers and eight skills, in one command.

Skills

Packaged workflows the server can load on demand.