<div align="center">

# 🌐 Google Trends MCP Server

**The Real-Time Google Trends Model Context Protocol (MCP) Server for AI Assistants.**

Connect **Claude Desktop**, **Cursor**, **Antigravity**, **Windsurf**, and **Cline** directly to live global search trends, breaking news, publisher sources, and extracted article summaries.

[![MCP Protocol](https://img.shields.io/badge/MCP-Model_Context_Protocol-blueviolet?style=for-the-badge&logo=anthropic)](https://modelcontextprotocol.io)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=for-the-badge&logo=node.js)](https://nodejs.org/)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue?style=for-the-badge)](LICENSE)
[![Zero Config](https://img.shields.io/badge/Zero--Config-Instant_Boot-orange?style=for-the-badge)](https://trends.google.com)

[Features](#-features) • [Installation](#-quick-start) • [Client Setup](#-ai-client-setup-guides) • [Tools](#-available-mcp-tools) • [Resources](#-mcp-resources) • [Prompts](#-mcp-prompts) • [Docker](#-docker-deployment)

</div>

---

## ⚡ Highlights & Features

- ⚡ **Zero-Config & Instant Boot (~150-300ms):** No database (PostgreSQL) or Redis cache setup required. Runs out-of-the-box directly querying Google Trends real-time streams.
- 📰 **Automated Article Summaries & Sources:** Fetches not only trend queries, but also news headlines, publisher/source names, direct source links, and automatically extracted article summaries.
- 📖 **Deep Article Reader:** Powered by Cheerio and Playwright with Ghostery ad-blocking to read, clean, and convert any news article into clean text/markdown for the LLM.
- 🌍 **Global Coverage (~250 Countries):** Query trends across all ISO 3166-1 alpha-2 country codes (TR, US, GB, DE, FR, JP, CA, etc.).
- 🏷️ **Category Filtering:** Filter by `all`, `business`, `tech` (Sci/Tech), `sports`, `health`, `entertainment`, and `top` stories.
- 🔌 **Dual Transports:**
  - **`stdio`** (Default): Standard input/output for local desktop clients (Claude Desktop, Cursor, Antigravity, Cline).
  - **`SSE`** (Server-Sent Events): HTTP transport on port `3333` for remote microservices and distributed agents.

---

## 🏗️ Architecture

```
┌────────────────────────────────────────────────────────────────────────┐
│             AI Assistants (Claude Desktop, Cursor, Antigravity, Cline) │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │  JSON-RPC 2.0 (stdio / SSE)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   Google Trends MCP Server (bin/mcp-server.js)         │
│          • Tools (Trends, Article Reader, Metadata)                    │
│          • Resources (trends://latest, trends://countries)             │
│          • Prompts (analyze_trends, trend_deep_dive)                   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   Real-Time Fetch & Article Engine                     │
│   • Live Google Trends RSS / JSON Stream Parser (~200ms)               │
│   • Concurrent HTML Metadata & Summary Extractor                       │
│   • Headless Chromium (Playwright + AdBlocker) Web Reader Fallback     │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 🚀 Quick Start

### 1. Direct Run with npx / node

You can run the MCP server immediately without installing any external services:

```bash
# Clone the repository
git clone https://github.com/yusuf-polat/Google-Trends.git
cd Google-Trends

# Install dependencies
npm install

# Start in stdio mode (Default for AI Desktop clients)
npm start

# Or start in HTTP SSE mode
npm run mcp:sse
```

### 2. Browser Testing via MCP Inspector

Test all tools interactively in your browser with the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node bin/mcp-server.js
```

---

## 🔌 AI Client Setup Guides

### 1. Claude Desktop
Add the server configuration to your `claude_desktop_config.json`:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "node",
      "args": ["<PATH-TO-REPO>/bin/mcp-server.js"]
    }
  }
}
```
*(Replace `<PATH-TO-REPO>` with your absolute path, e.g. `D:/Google-Trends`)*

---

### 2. Cursor IDE
Create or edit `.cursor/mcp.json` in your project or global directory:

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "node",
      "args": ["<PATH-TO-REPO>/bin/mcp-server.js"]
    }
  }
}
```
*Or go to **Settings > Features > MCP > Add New MCP Server** and select `command`.*

---

### 3. Antigravity IDE
Add to your global `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "node",
      "args": ["<PATH-TO-REPO>/bin/mcp-server.js"]
    }
  }
}
```

---

### 4. VS Code (Cline / Roo Code / Continue)
In your Cline / Roo Code extension settings (`cline_mcp_settings.json`):

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "node",
      "args": ["<PATH-TO-REPO>/bin/mcp-server.js"]
    }
  }
}
```

---

## 🛠️ Available MCP Tools

### 1. `get_realtime_trends`
Fetch live trending topics and searches with approximate search volume, breakdown queries, publisher sources, and extracted article summaries.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `country` | `string` | No | 2-letter ISO country code (e.g. `TR`, `US`, `GB`, `DE`). Default: `TR`. |
| `category` | `string` | No | Category filter: `all`, `business`, `entertainment`, `health`, `tech`, `sports`, `top`. Default: `all`. |
| `search` | `string` | No | Optional keyword query to filter results. |
| `limit` | `number` | No | Maximum trends to return (1-100). Default: `20`. |
| `include_summaries` | `boolean` | No | Automatically extract real article summaries for news items. Default: `true`. |

**Sample Response:**
```json
{
  "source": "google_trends_realtime_rss",
  "country": "TR",
  "country_name": "Türkiye (Turkey)",
  "returned_count": 1,
  "trends": [
    {
      "trend_name": "sıla türkoğlu",
      "search_volume": "5000+",
      "published_at": "Thu, 17 Sep 2026 07:20:00 -0700",
      "news": [
        {
          "title": "650 bin TL'lik davada mahkeme kararını verdi",
          "publisher": "Sözcü Gazetesi",
          "url": "https://www.sozcu.com.tr/...",
          "summary": "Sıla Türkoğlu'nun Kanal 7'de yayınlanan 'Emanet' dizisinden ayrılmasının ardından açılan davada mahkeme kararını verdi...",
          "cover_image": "https://sozcu01.sozcucdn.com/..."
        }
      ]
    }
  ]
}
```

---

### 2. `get_trend_details`
Get an in-depth breakdown of a single trending topic, inspecting all of its associated news stories with full summaries and publishers.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `trend_name` | `string` | **Yes** | The trending topic name to inspect. |
| `country` | `string` | No | Country code. Default: `TR`. |

---

### 3. `extract_article_content`
Extract clean full-text content, headline, summary, and metadata from any news URL linked to a trend. Automatically bypasses cookie popups and ad blocks.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | `string` | **Yes** | Direct HTTP/HTTPS URL of the article. |

---

### 4. `list_supported_countries`
List all ~250 ISO 3166-1 alpha-2 country codes and country names supported by Google Trends.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `filter` | `string` | No | Case-insensitive filter by country code or name. |

---

### 5. `list_supported_categories`
List supported Google Trends category shortcuts (`business`, `entertainment`, `health`, `tech`, `sports`, `top`).

---

### 6. `get_trends_stats`
Returns system operational metrics and engine capability summary.

---

## 📦 MCP Resources

Clients can read live resources directly without invoking tool arguments:

| URI | Name | Description |
|---|---|---|
| `trends://latest` | Latest Trending Topics | Real-time stream of top trending searches in JSON format. |
| `trends://countries` | Supported Countries | Complete ISO country code directory. |
| `trends://categories` | Supported Categories | Category identifiers and descriptions. |
| `trends://stats` | Engine Stats | System status and supported features. |

---

## 💡 MCP Prompts

Pre-engineered prompt templates for AI workflows:

- **`analyze_trends`**: Guides the AI to fetch current trends, cluster them into thematic domains (Politics, Tech, Markets, Entertainment), and produce an executive briefing.
- **`trend_deep_dive`**: Instructs the AI to perform investigative reporting on a specific trend, reading linked articles and identifying stakeholders, timelines, and perspectives.

---

## 🐳 Docker Deployment

To run Google Trends MCP as an isolated container:

```bash
# Build Docker image
docker build -t google-trends-mcp .

# Run in SSE HTTP mode (Port 3333)
docker run -d -p 3333:3333 --name google-trends-mcp google-trends-mcp npm run mcp:sse
```

Once running, configure remote MCP clients using the SSE URL:
`http://localhost:3333/sse`

---

## 💬 Example Prompt Interactions

Ask your AI assistant naturally:

> **User:** *"What are the top 5 trending topics in Turkey right now, and what are their search volumes?"*
> *(Assistant calls `get_realtime_trends` with `country: "TR"`, `limit: 5`)*

> **User:** *"What's trending in Tech in the United States today? Summarize the main article for the #1 topic."*
> *(Assistant calls `get_realtime_trends` with `country: "US"`, `category: "tech"` and summarizes the news)*

> **User:** *"Read this news article from the trend and give me the full breakdown: https://..."*
> *(Assistant calls `extract_article_content`)*

---

## 📄 License

This project is licensed under the [ISC License](LICENSE).
Made with ❤️ for the open-source MCP and AI community.