Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GDELT MCP Server search for articles about climate change in the past month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides access to the GDELT DOC 2.0 API for searching global news articles and images.
Search Articles: Search across 65 languages of global news coverage (3 months rolling window)
Search Images: Query the Visual Knowledge Graph (VGKG) for news imagery
Custom Defaults: Optimized defaults (ArtList mode, JSON format, 50 records, newest first, 1 month timespan)
Boolean Queries: Support for OR, AND operators and exact phrase matching
Flexible Timespan: Search from 1 hour to 3 months of coverage
Related MCP server: gdelt-events-mcp
npm install
npm run buildThe server can be configured using environment variables. Create a .env file:
cp .env.example .envAvailable options:
GDELT_API_TIMEOUT: API request timeout in milliseconds (default: 30000)
GDELT_API_BASE_URL: GDELT API base URL (default: https://api.gdeltproject.org/api/v2/doc/doc)
GDELT_DEFAULT_MAX_RECORDS: Default maximum records to return (default: 50)
GDELT_DEFAULT_TIMESPAN: Default time period for searches (default: 1month)
GDELT_USER_AGENT: User agent string (default: GDELT-MCP-Server/1.0)
LOG_LEVEL: Logging level - debug, info, warn, error (default: info)
This MCP server is designed to be used with MCP-compatible clients. Add it to your MCP client configuration:
{
"mcpServers": {
"gdelt": {
"command": "node",
"args": ["/path/to/gdelt-mcp-server/dist/index.js"]
}
}
}Search GDELT's global news database for articles.
Parameters:
query (required): Search query with support for:
Exact phrases: "climate change"
OR operator: climate OR environment
AND operator: climate AND policy
maxRecords (optional): Number of results (1-250, default: 50)
timespan (optional): Time period like "1month", "7d", "24h" (default: "1month")
sort (optional): Sort order - DateDesc, DateAsc, ToneAsc, ToneDesc, HybridRel
startDateTime (optional): Start date in YYYYMMDDHHMMSS format
endDateTime (optional): End date in YYYYMMDDHHMMSS format
Example:
{
"query": "\"climate change\" OR \"global warming\"",
"maxRecords": 25,
"timespan": "7d"
}Search GDELT's Visual Knowledge Graph for news images.
Parameters:
query (required): Search term (e.g., "fire", "protest", "flood")
maxRecords (optional): Number of images (1-250, default: 50)
timespan (optional): Time period (default: "1month")
imageType (optional):
imagetag: Search by visual content (what the AI sees in the image)
imagewebtag: Search by caption/context text
imageocrmeta: Search by OCR text and metadata
Example:
{
"query": "wildfire",
"maxRecords": 30,
"imageType": "imagetag",
"timespan": "7d"
}This server uses the GDELT DOC 2.0 API which provides:
Rolling 3-month window of coverage (back to January 2017)
65 languages with English search terms
Deep learning-powered image analysis
Real-time and historical news data
MIT
Search GDELT's global news database for articles across 65 languages. Supports keyword/phrase searches, Boolean operators (OR, AND), and searches back 3 months. Default returns 50 most recent articles from the past month.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (supports keywords, phrases in quotes, OR/AND operators) | |
| maxRecords | No | Maximum number of articles to return (1-250, default: 50) | |
| timespan | No | Time period to search (e.g., "1month", "7d", "24h", default: "1month") | |
| sort | No | Sort order (default: DateDesc) | |
| startDateTime | No | Start date in YYYYMMDDHHMMSS format | |
| endDateTime | No | End date in YYYYMMDDHHMMSS format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: search capabilities (Boolean, phrases), time range (3 months back), and default behavior (50 most recent articles from past month). It doesn't mention rate limits or auth but these are acceptable for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted verbiage. The description is front-loaded with purpose and quickly covers key features and defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains core functionality but fails to mention what fields the returned articles contain. With no output schema, this is a gap for an agent needing complete understanding of tool output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the query parameter supports Boolean operators and giving default context for maxRecords and timespan (50 most recent, past month).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches GDELT's global news database for articles across 65 languages, specifying verb and resource. It distinguishes from sibling tool search_images by focusing on articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use (searching news articles) but does not explicitly contrast with alternatives or state when not to use. The sibling tool name suggests different content type, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GDELT's Visual Knowledge Graph (VGKG) for news images. Can search by visual content (what's depicted), captions/context, or OCR/metadata. Searches back 3 months of global news imagery.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query for images | |
| maxRecords | No | Maximum number of images to return (1-250, default: 50) | |
| timespan | No | Time period to search (default: "1month") | |
| imageType | No | Image search type: imagetag (visual content), imagewebtag (caption/context), imageocrmeta (OCR/metadata) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a 3-month time scope, which is useful, but does not specify read-only behavior, authentication needs, rate limits, or other behavioral traits. For a search tool, read-only is assumed but not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, no wasted words. It front-loads the core purpose and then provides additional details, making it easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the high-level functionality and search modes, but fails to describe the return format or structure of results. With no output schema, the agent may need to infer what fields are returned (e.g., URLs, metadata). This gap affects completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already described. The description adds context about the 3-month limit and global imagery, but does not significantly enhance understanding beyond the schema for individual parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches GDELT's Visual Knowledge Graph for news images, with three distinct search modes. It differentiates from the sibling tool 'search_articles' by focusing on images, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool (searching news images) and mentions the three search types, but does not explicitly state when not to use it or provide direct comparison with the sibling tool. However, the distinction between image and article search is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0search_articlessearch_imagesEach tool targets a distinct resource: articles vs. images. There is no overlap in purpose.
Both tools follow a consistent 'search_' prefix with a noun, adhering to verb_noun naming.
With only two tools, the server feels somewhat thin but remains focused. The count is borderline for its scope.
The server covers its primary domain of search (articles and images) adequately. Minor gaps like fetching specific article details are absent but not critical for a search-focused server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.
Geopolitical event detection, tone timeseries, actor trends from GDELT 2.0.
Real-time news search across 500,000+ sources in 60+ languages with sentiment and entities.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MissionSquad/mcp-gdelt'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
