@unclick/gdelt-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright (c) 2026 UnClick / malamutemayhem
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,36 @@
+# GDELT News MCP by UnClick
+
+Global news search, events, tone, themes, and geographic signals from GDELT.
+
+> By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+
+## Install
+
+Installs straight from GitHub, no npm account needed.
+
+```json
+{
+  "mcpServers": {
+    "gdelt": {
+      "command": "npx",
+      "args": ["-y", "https://github.com/malamutemayhem/unclick/releases/download/standalone-mcps-latest/gdelt.tgz"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `gdelt_news_search`
+- `gdelt_tone_analysis`
+- `gdelt_geo_events`
+- `gdelt_trending`
+
+## Want the rest?
+
+This is one connector. [UnClick](https://unclick.world) bundles 180+ tools plus
+persistent cross-session agent memory in a single install.
+
+## License
+
+Apache-2.0

package/dist/gdelt-tool.js

@@ -0,0 +1,176 @@
+// GDELT Project integration - global news intelligence, no auth required.
+// Docs: https://www.gdeltproject.org/
+// DOC API: https://api.gdeltproject.org/api/v2/doc/doc
+// GEO API: https://api.gdeltproject.org/api/v2/geo/geo
+// Updated every 15 minutes. Covers all broadcast, print, and web news globally.
+const GDELT_DOC = "https://api.gdeltproject.org/api/v2/doc/doc";
+const GDELT_GEO = "https://api.gdeltproject.org/api/v2/geo/geo";
+// ─── API helpers ──────────────────────────────────────────────────────────────
+async function gdeltFetch(base, params) {
+    const url = `${base}?${params}`;
+    const res = await fetch(url, {
+        headers: { "User-Agent": "UnClickMCP/1.0 (https://unclick.io)" },
+    });
+    if (!res.ok)
+        throw new Error(`GDELT API HTTP ${res.status}`);
+    return res.json();
+}
+// ─── gdelt_news_search ────────────────────────────────────────────────────────
+export async function gdeltNewsSearch(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        return { error: "query is required." };
+    const maxrecords = Math.min(250, Math.max(1, Number(args.maxrecords ?? 25)));
+    const params = new URLSearchParams({
+        query,
+        mode: "artlist",
+        format: "json",
+        maxrecords: String(maxrecords),
+    });
+    if (args.startdatetime)
+        params.set("startdatetime", String(args.startdatetime));
+    if (args.enddatetime)
+        params.set("enddatetime", String(args.enddatetime));
+    if (args.sourcelang)
+        params.set("sourcelang", String(args.sourcelang));
+    if (args.sourcecountry)
+        params.set("sourcecountry", String(args.sourcecountry));
+    const data = await gdeltFetch(GDELT_DOC, params);
+    const articles = data?.articles ?? [];
+    return {
+        query,
+        count: articles.length,
+        articles: articles.map((a) => ({
+            title: a.title ?? null,
+            url: a.url ?? null,
+            domain: a.domain ?? null,
+            date: a.seendate ?? null,
+            language: a.language ?? null,
+            country: a.sourcecountry ?? null,
+            image: a.socialimage ?? null,
+        })),
+    };
+}
+// ─── gdelt_tone_analysis ──────────────────────────────────────────────────────
+// Uses timelinetone mode - returns average tone score over time.
+// Negative values = negative sentiment; positive = positive sentiment.
+export async function gdeltToneAnalysis(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        return { error: "query is required." };
+    const params = new URLSearchParams({
+        query,
+        mode: "timelinetone",
+        format: "json",
+    });
+    if (args.timespan)
+        params.set("timespan", String(args.timespan));
+    if (args.sourcelang)
+        params.set("sourcelang", String(args.sourcelang));
+    if (args.sourcecountry)
+        params.set("sourcecountry", String(args.sourcecountry));
+    const data = await gdeltFetch(GDELT_DOC, params);
+    const timelineArr = data?.timeline ?? [];
+    const entries = timelineArr.flatMap((t) => t?.data ?? []);
+    if (entries.length === 0) {
+        return { query, timeline: [], summary: null };
+    }
+    const values = entries.map((e) => e.value ?? 0).filter((v) => !isNaN(v));
+    const avg = values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0;
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const latest = entries[entries.length - 1];
+    return {
+        query,
+        summary: {
+            average_tone: Math.round(avg * 100) / 100,
+            min_tone: Math.round(min * 100) / 100,
+            max_tone: Math.round(max * 100) / 100,
+            latest_tone: Math.round((latest?.value ?? 0) * 100) / 100,
+            latest_date: latest?.date ?? null,
+            interpretation: avg < -2 ? "strongly negative" :
+                avg < -0.5 ? "slightly negative" :
+                    avg < 0.5 ? "neutral" :
+                        avg < 2 ? "slightly positive" : "strongly positive",
+        },
+        timeline: entries.slice(-30).map((e) => ({
+            date: e.date ?? null,
+            tone: Math.round((e.value ?? 0) * 100) / 100,
+        })),
+    };
+}
+// ─── gdelt_geo_events ─────────────────────────────────────────────────────────
+// Uses the GDELT GEO API - returns geographic event clusters with article counts and tone.
+export async function gdeltGeoEvents(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        return { error: "query is required." };
+    const maxpoints = Math.min(250, Math.max(1, Number(args.maxpoints ?? 50)));
+    const params = new URLSearchParams({
+        query,
+        format: "json",
+        maxpoints: String(maxpoints),
+    });
+    if (args.timespan)
+        params.set("timespan", String(args.timespan));
+    const data = await gdeltFetch(GDELT_GEO, params);
+    const features = data?.features ?? [];
+    return {
+        query,
+        count: features.length,
+        events: features.map((f) => ({
+            name: f.properties?.name ?? null,
+            country: f.properties?.countrycode ?? null,
+            coordinates: f.geometry?.coordinates
+                ? { lat: f.geometry.coordinates[1], lng: f.geometry.coordinates[0] }
+                : null,
+            article_count: f.properties?.count ?? 0,
+            tone: f.properties?.tone != null
+                ? Math.round(f.properties.tone * 100) / 100
+                : null,
+        })).sort((a, b) => (b.article_count ?? 0) - (a.article_count ?? 0)),
+    };
+}
+// ─── gdelt_trending ───────────────────────────────────────────────────────────
+// Uses timelinevol mode - returns article volume over time for a query.
+// Shows whether a topic is surging, stable, or fading in the news cycle.
+export async function gdeltTrending(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        return { error: "query is required." };
+    const params = new URLSearchParams({
+        query,
+        mode: "timelinevol",
+        format: "json",
+    });
+    if (args.timespan)
+        params.set("timespan", String(args.timespan));
+    if (args.sourcelang)
+        params.set("sourcelang", String(args.sourcelang));
+    const data = await gdeltFetch(GDELT_DOC, params);
+    const timelineArr = data?.timeline ?? [];
+    const entries = timelineArr.flatMap((t) => t?.data ?? []);
+    if (entries.length === 0) {
+        return { query, trend: "no data", timeline: [] };
+    }
+    const values = entries.map((e) => e.normvalue ?? e.value ?? 0);
+    const recent = values.slice(-5);
+    const older = values.slice(0, Math.max(1, values.length - 5));
+    const recentAvg = recent.reduce((a, b) => a + b, 0) / recent.length;
+    const olderAvg = older.reduce((a, b) => a + b, 0) / older.length;
+    const trend = olderAvg === 0 ? "emerging" :
+        recentAvg > olderAvg * 1.5 ? "surging" :
+            recentAvg > olderAvg * 1.1 ? "rising" :
+                recentAvg < olderAvg * 0.5 ? "fading" :
+                    recentAvg < olderAvg * 0.9 ? "declining" : "stable";
+    return {
+        query,
+        trend,
+        recent_avg_volume: Math.round(recentAvg * 1000) / 1000,
+        older_avg_volume: Math.round(olderAvg * 1000) / 1000,
+        timeline: entries.map((e) => ({
+            date: e.date ?? null,
+            volume: Math.round((e.normvalue ?? e.value ?? 0) * 1000) / 1000,
+        })),
+    };
+}

package/dist/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// GDELT News MCP. Standalone MCP server by UnClick.
+// By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+//
+// Generated from the UnClick connector by scripts/generate-standalone-mcp.mjs.
+// Edit the connector in the UnClick monorepo, not here.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { gdeltNewsSearch, gdeltToneAnalysis, gdeltGeoEvents, gdeltTrending, } from "./gdelt-tool.js";
+const TOOLS = [
+    {
+        name: "gdelt_news_search",
+        description: "Search global news via the GDELT Project. Returns article titles, URLs, sources, dates, countries, and languages. No API key required.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Search query (keywords, phrases, or operators)" },
+                maxrecords: { type: "number", description: "Max articles to return (default 25, max 250)" },
+                startdatetime: { type: "string", description: "Start datetime YYYYMMDDHHMMSS (UTC)" },
+                enddatetime: { type: "string", description: "End datetime YYYYMMDDHHMMSS (UTC)" },
+                sourcelang: { type: "string", description: "Filter by source language (e.g. 'english', 'spanish')" },
+                sourcecountry: { type: "string", description: "Filter by source country code (e.g. 'US', 'GB', 'AU')" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "gdelt_tone_analysis",
+        description: "Analyse the sentiment and tone of global news coverage for a topic over time. Returns average tone scores (negative = negative coverage, positive = positive), trend summary, and timeline. Great for brand monitoring or tracking public sentiment.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Topic or keyword to analyse" },
+                timespan: { type: "string", description: "Time window (e.g. '24h', '7d', '1month')" },
+                sourcelang: { type: "string", description: "Filter by source language" },
+                sourcecountry: { type: "string", description: "Filter by source country code" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "gdelt_geo_events",
+        description: "Get geographic distribution of news events for a topic from the GDELT GEO API. Returns event clusters with location, article count, and tone score.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Topic or keyword to map" },
+                maxpoints: { type: "number", description: "Max location clusters to return (default 50, max 250)" },
+                timespan: { type: "string", description: "Time window (e.g. '24h', '7d')" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "gdelt_trending",
+        description: "Check whether a topic is trending in global news using GDELT article volume timelines. Returns a trend classification (surging, rising, stable, declining, fading) and volume data over time.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Topic or keyword to check" },
+                timespan: { type: "string", description: "Time window (e.g. '24h', '7d', '1month')" },
+                sourcelang: { type: "string", description: "Filter by source language" },
+            },
+            required: ["query"],
+        },
+    }
+];
+const HANDLERS = {
+    gdelt_news_search: (args) => gdeltNewsSearch(args),
+    gdelt_tone_analysis: (args) => gdeltToneAnalysis(args),
+    gdelt_geo_events: (args) => gdeltGeoEvents(args),
+    gdelt_trending: (args) => gdeltTrending(args),
+};
+const server = new Server({ name: "io.github.malamutemayhem/gdelt", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const handler = HANDLERS[req.params.name];
+    if (!handler) {
+        return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    try {
+        const result = await handler((req.params.arguments ?? {}));
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[gdelt-mcp] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@unclick/gdelt-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.malamutemayhem/gdelt",
+  "description": "Global news search, events, tone, themes, and geographic signals from GDELT. By UnClick (https://unclick.world).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "unclick",
+    "gdelt",
+    "news",
+    "events"
+  ],
+  "author": "UnClick (https://unclick.world)",
+  "type": "module",
+  "bin": {
+    "gdelt-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "directory": "packages/standalone/gdelt-mcp"
+  },
+  "homepage": "https://unclick.world"
+}

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.malamutemayhem/gdelt",
+  "title": "GDELT News MCP by UnClick",
+  "description": "Global news search, events, tone, themes, and geographic signals from GDELT. By UnClick.",
+  "version": "0.1.0",
+  "websiteUrl": "https://unclick.world",
+  "icons": [
+    {
+      "src": "https://unclick.world/favicon.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ]
+    }
+  ],
+  "repository": {
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "source": "github",
+    "subfolder": "packages/standalone/gdelt-mcp"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@unclick/gdelt-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}