mcp-trendpulse

TrendPulse is a Python Model Context Protocol (MCP) server for researching current news and search-interest trends. It combines Google News discovery and article extraction with Google Trends analysis so MCP clients can inspect what is trending, compare keyword momentum, explore related demand, and add current-news context to research workflows.

The project currently ships as a community/self-hosted MCP server and also contains the implementation for a separate hosted TrendPulse by DigestSEO surface for remote MCP clients such as ChatGPT and Codex. The hosted layer uses a smaller, goal-oriented tool surface while the community server keeps the full low-level research toolkit available to developers.

Project status: the local/community server is usable today. The DigestSEO-hosted MCP and public OpenAI plugin are not released yet and should not be treated as available endpoints.

Engineering context: TrendPulse is part of the DigestSEO MCP ecosystem. It complements mcp-gsc for Google Search Console data, mcp-geo for AI visibility, and mcp-web-validator for technical web validation. The broader architecture is documented in the DigestSEO MCP Suite engineering case study.

TrendPulse Demand Brief

Need a fast evidence check before choosing a topic, keyword, market, product angle, or content bet? Tomi offers a human-produced TrendPulse Demand Brief for EUR 49.

For one decision, the brief covers up to five keywords/phrases and two geographic markets using TrendPulse's open-source research capabilities plus current public sources: search-interest direction, relative momentum, related demand, useful news context, and three concrete implications. Target turnaround is within 24 hours after payment is confirmed and the inputs are supplied.

See the exact scope and request format, read a public sample brief, or email info@tomiseregi.si with the subject TrendPulse Demand Brief [TP-RS1].

The paid brief is optional. The Community MCP remains free and unchanged, and the TP-RS1 marker is only an inbound attribution marker; no hidden telemetry is added to the MCP.

What TrendPulse can do

News research

• Search Google News by keyword, location, topic, or publisher domain.
• Retrieve top news stories.
• Resolve Google News links and extract article content.
• Fall back from normal HTTP retrieval to Playwright/Chromium for difficult pages.
• Optionally summarize article text with MCP client sampling, with local NLP as a fallback.

Trend research

• Retrieve current trending terms for a geographic market.
• Pull Google Trends interest-over-time data for one or more keywords.
• Calculate keyword growth over custom windows such as 3M or 1Y.
• Rank live trends by volume or growth.
• Inspect interest by country, region, city, or DMA where supported.
• Explore related queries, related topics, suggestions, and category IDs.
• Compare Google Search, YouTube Search, News Search, Image Search, and Google Shopping trend properties where supported by the underlying provider.

Community and hosted architecture

TrendPulse is being developed with two deliberate surfaces:

The community server remains useful independently. The hosted edition will reuse the same core trend-research concepts while adding the deployment, reliability, authentication, observability, and product integration needed for a managed service.

The implemented hosted tool surface is intentionally higher level than the community API and centers on goals such as:

• discover_trends
• analyze_keyword_trend
• compare_keyword_trends
• discover_related_demand
• get_trend_context
• find_seo_opportunities

These names describe the hosted ChatGPT Apps/MCP interface; they remain separate from the current Community MCP tool names.

Installation

Run from PyPI with uvx (recommended)

TrendPulse is published on PyPI, so the shortest install path is:

uvx mcp-trendpulse

Python 3.11 or newer is required. Python 3.10 reached end-of-life in October 2026 and cannot use Pillow 13, which patches upstream image-decoder vulnerabilities. To run TrendPulse on a machine with Python 3.10 as its default, select a supported interpreter explicitly:

uvx --python 3.11 mcp-trendpulse

See the security policy for the supported-runtime decision. Users on Python 3.10 must upgrade their interpreter; the new package will not install into a Python 3.10-only environment.

To run the current repository head instead of the published package:

uvx --from git+https://github.com/AKzar1el/mcp-trendpulse.git mcp-trendpulse

Install with pip from a checkout

git clone https://github.com/AKzar1el/mcp-trendpulse.git
cd mcp-trendpulse
python -m pip install .
python -m mcp_trendpulse

Article download safety and optional Chromium

Article downloads use bounded HTTP(S) requests pinned to a validated public IP, while retaining the original hostname for the HTTP Host header and HTTPS certificate verification. System proxies are disabled for this path. The Playwright article fallback is currently disabled because browser URL interception alone cannot guarantee connection-level protection against DNS rebinding; JavaScript-only or challenge-protected articles may therefore return no content. Other Google Trends/News discovery operations are unaffected.

The optional Python playwright package does not install Chromium automatically. For separate browser-supported workflows, install Chromium as follows:

For local use:

playwright install chromium

For Linux environments that also require browser system dependencies:

playwright install --with-deps chromium

Trend-only operations do not inherently require Chromium.

Client configuration

Claude Desktop and Claude Code

Claude Code plugin packaging is included in .claude-plugin/plugin.json with its MCP definition in .mcp.json. The Community MCP remains local/stdin-based and runs through uvx mcp-trendpulse.

Claude Desktop

Using the published PyPI package with uvx:

{
  "mcpServers": {
    "mcp-trendpulse": {
      "command": "uvx",
      "args": ["mcp-trendpulse"]
    }
  }
}

VS Code

Install TrendPulse in VS Code

Requires uv/uvx. The install runs the published Community MCP package from PyPI over local stdio.

For workspace-level configuration, put this in .vscode/mcp.json. The same top-level servers shape is used by the VS Code user-profile mcp.json for a global configuration.

{
  "servers": {
    "mcp-trendpulse": {
      "command": "uvx",
      "args": ["mcp-trendpulse"]
    }
  }
}

Codex CLI and Codex IDE extension

Codex CLI and the Codex IDE extension share MCP configuration and support local stdio servers. Register the published TrendPulse Community MCP package with:

codex mcp add mcp-trendpulse -- uvx mcp-trendpulse

This makes TrendPulse available to Codex CLI and its IDE extension; it does not automatically install the server in ChatGPT desktop or web. See OpenAI's Codex MCP guidance for the shared Codex configuration model.

ChatGPT custom MCP connections

ChatGPT uses a separate plugin connection workflow; it does not import the local Codex MCP registration above. Where permitted by your account and workspace, use Plugins -> Add custom MCP server with a reachable HTTPS Streamable HTTP endpoint, or an available Secure MCP Tunnel for a private server. See OpenAI's connection instructions for current requirements and access controls.

Local stdio execution through a desktop-only ChatGPT plugin is a distinct, partner-allowlisted submission route, not a general Settings -> MCP Servers command-entry option. See OpenAI's desktop-only plugin policy.

TrendPulse's managed HTTPS endpoint and public ChatGPT plugin are not released. The current published Community MCP runs locally via uvx mcp-trendpulse in supported stdio clients; the Codex command alone does not connect it to ChatGPT.

Cursor and portable Agent Plugins

This repository includes an Agent Plugins 1.0 manifest at the repository root. Compatible clients such as Cursor and GitHub Copilot can load the same portable plugin.json + mcp.json package.

Cursor also supports global and project MCP configuration. Add the server to the relevant mcp.json configuration:

{
  "mcpServers": {
    "mcp-trendpulse": {
      "command": "uvx",
      "args": ["mcp-trendpulse"]
    }
  }
}

Devin CLI and Devin Desktop

Devin CLI plugins can load Claude plugin packages and Agent Plugins 1.0 packages directly from GitHub. TrendPulse already ships both compatible layouts (.claude-plugin/plugin.json + .mcp.json, and root plugin.json + mcp.json). Install it with:

devin plugins install AKzar1el/mcp-trendpulse

Devin requires a signed-in CLI session to manage plugins. The installed TrendPulse plugin starts the published Community MCP locally over stdio with uvx mcp-trendpulse; it does not use the unreleased hosted TrendPulse endpoint. The same plugin is available in Devin Desktop after installation.

Kiro

Requires uv/uvx. The install runs the published Community MCP package from PyPI; it does not use the unreleased hosted surface.

Privacy: TrendPulse Community MCP Privacy Notice · Support: info@tomiseregi.si

LM Studio

Add TrendPulse to LM Studio

Requires uv/uvx. LM Studio runs the published Community MCP package locally over stdio; no hosted TrendPulse service is required.

ChatGPT web and other cloud MCP clients

The repository now includes a dedicated stateless Streamable HTTP ASGI entry point at mcp_trendpulse.asgi:app. This is separate from the Community stdio entry point, which remains unchanged.

For controlled local/private testing you can run the ASGI app with Uvicorn or use the provided container. See deploy/README.md for the hardened container, Host/Origin allowlists, Chromium sandbox requirements, health/readiness endpoints, and reverse-proxy notes.

The DigestSEO-hosted endpoint and public ChatGPT app are still not released. Hosted deployments now support fail-closed Clerk OAuth authentication; do not expose the remote transport publicly unless Clerk issuer/JWKS/audience settings, the public base URL, and the Host/Origin allowlists are configured for that deployment.

Configuration

TrendPulse loads environment variables from the process environment and from a local .env file when present.

Useful variables include:

HTTP_PROXY=http://your-proxy-address:port
HTTPS_PROXY=http://your-proxy-address:port
GOOGLE_NEWS_LANGUAGE=en
GOOGLE_NEWS_COUNTRY=US
GOOGLE_TRENDS_DELAY=2.0
# Optional, absolute, private directory shared by TrendPulse processes on one host:
# TRENDPULSE_SHARED_STATE_DIR=/home/you/.cache/mcp-trendpulse

GOOGLE_NEWS_LANGUAGE and GOOGLE_NEWS_COUNTRY select the Google News language/edition used by all news-discovery tools; defaults remain en and US. GOOGLE_TRENDS_DELAY (default 2 seconds) paces Google Trends requests across all TrendSpy worker threads in one process, including the Trending Now batch endpoint. Identical interest-over-time queries are reused from a bounded, 90-second in-memory cache; concurrent duplicates share one provider request. After an upstream 429 or detected embedded quota rejection, the process pauses new Trends calls with bounded exponential cooldown and honors Retry-After when supplied. An already-cached series may still be returned during cooldown. The process also emits privacy-safe aggregate provider counters and latency buckets (see docs/operations.md). By default, coordination is process-local; it cannot increase or bypass Google's unpublished quota or throttle Google News article fetching. Proxy variables can be useful for legitimate network configuration but do not guarantee a higher upstream quota.

For multiple local agents on one computer, set the optional TRENDPULSE_SHARED_STATE_DIR to the same absolute, user-private directory in every TrendPulse process. This adds SQLite-backed inter-process pacing, a maximum 12-second request queue, shared 429 cooldown, and a 256-entry cache of numeric, indexed Google Trends time series. Cache keys are HMAC-hashed with a private directory key; query text and news articles are not saved. Long-window series live at most two hours, annual windows 90 minutes, shorter windows 30 minutes, and near-real-time series two minutes. Use a local disk, not a network drive or independent container filesystems. If shared state is unavailable, the existing in-process protections continue operating and emit a sanitized warning. The feature is off by default; it cannot raise Google's provider quotas or provide coordination across separate hosts.

Remote deployments also support TRENDPULSE_HTTP_PATH, TRENDPULSE_HTTP_ALLOWED_HOSTS, TRENDPULSE_HTTP_ALLOWED_ORIGINS, and TRENDPULSE_BROWSER_SANDBOX. The container enables Chromium sandboxing explicitly; local Community runs retain the Playwright-compatible default unless you opt in.

Do not commit secrets, private proxy credentials, or machine-specific .env files.

MCP tools

The community MCP server currently exposes 16 tools.

News tools

Trend tools

Example: explicit trend window

get_trends accepts an explicit timeframe. Supplying one is preferable when you need reproducible comparisons.

{
  "keyword": ["technical SEO audit", "AI SEO audit"],
  "geo": "US",
  "source": "google search",
  "timeframe": "today 12-m",
  "cat": 0
}

Supported provider ranges include standard windows such as today 12-m and today 5-y, relative windows such as today 90-d, all, and exact date ranges such as 2021-01-01 2026-01-01.

Google Trends values are normalized interest scores. Do not interpret a 0-100 interest series as absolute search volume.

CLI

The separate Click CLI is included in the public PyPI package. Run its published commands without a source checkout:

uvx --python 3.11 --from mcp-trendpulse mcp-trendpulse-cli --help

Published CLI (v0.2.43+): The site command and the --headlines-only options for keyword, location, topic, top, and site are available in the published PyPI package. Run the stable release rather than repository HEAD:

uvx --python 3.11 --from mcp-trendpulse mcp-trendpulse-cli keyword "OpenAI" --headlines-only

From a local source checkout, uv run mcp-trendpulse-cli --help uses that checkout. The opt-in headline-only commands return genuine Google News RSS titles, publishers, dates, and Google News links labeled as metadata, not extracted article bodies. Default news commands continue to attempt publisher-article extraction.

Source checkout (not yet in the published PyPI version): Extracted-article CLI commands print results without creating JSON files. To opt into file export, pass --save-json-dir with an existing directory, for example uv run mcp-trendpulse-cli keyword "OpenAI" --save-json-dir ./exports. Output filenames include a short URL hash to distinguish similarly titled articles; existing files are never overwritten, and duplicate destinations or export failures produce errors. The --headlines-only mode does not export article JSON.

The operator-only bigquery-sql command generates a fixed-table, partition-filtered SQL preview for Google's official public Top 25 / Rising datasets. It never submits a job or incurs API usage automatically. See docs/bigquery-trends.md for sandbox, query-cost guardrails, and market-coverage limitations.

watch provides opt-in local manual threshold rules and idempotent evaluation of user-supplied normalized interest evidence; it does not poll providers, schedule runs, or send external alerts. See docs/trend-watch.md before using the commands.

CLI commands available since v0.2.43 (also on GitHub main):

brief-pack
keyword
location
site
top
topic
trending

brief-pack emits the deterministic trend/growth evidence table used for Demand Brief fulfillment. It intentionally leaves the final interpretation and recommendations to the human-produced brief.

For a source-checkout workflow that consumes evidence programmatically, choose JSON instead of the default Markdown:

uv run mcp-trendpulse-cli brief-pack --keyword "ChatGPT" --keyword "Claude" --market US --format json > evidence.json

The JSON includes source attribution, the shared timeframe, per-market latest observation dates, numeric indices/growth percentages (or null when unavailable), and warnings about stale or malformed evidence. Indices are normalized within each market request; they are not search volume and should not be directly compared across markets. The command fetches Google Trends data but does not generate recommendations or send a Demand Brief.

The CLI and MCP surfaces are intentionally documented separately because they do not expose the same command set.

Development

Install the project with its development dependencies using your preferred Python environment, then run the unit suite:

python -m pytest

The default pytest configuration excludes live integration tests.

Run live provider tests explicitly with:

python -m pytest tests/integration -m integration

Browser-marked integration tests require Playwright Chromium to be installed.

Run Ruff checks with:

ruff check .

MCP Inspector

Run the published-from-GitHub server through the MCP Inspector:

npx @modelcontextprotocol/inspector uvx --from git+https://github.com/AKzar1el/mcp-trendpulse.git mcp-trendpulse

For a local checkout:

npx @modelcontextprotocol/inspector uv run mcp-trendpulse

Packaging

A GitHub Actions workflow builds and publishes Python distributions through PyPI Trusted Publishing when a GitHub release is published. The current stable package can be run with uvx mcp-trendpulse; use the GitHub uvx --from ... form only when you intentionally want repository-head code.

Security notes

Article retrieval is an outbound network feature and is treated as untrusted input. The implementation validates HTTP(S) targets, rejects private and non-routable destinations, checks redirect targets, enforces response-size limits, and applies browser-route validation when Playwright is used.

If you deploy TrendPulse remotely, retain these controls and add deployment-level rate limiting, request timeouts, observability, and resource limits rather than relying only on application defaults.

For responsible disclosure instructions, see SECURITY.md.

Roadmap

Current production-readiness priorities are:

1. Keep documentation, packaging metadata, and generated MCP manifests coherent with the live tool surface.
2. Keep CI, package validation, and dependency/runtime coverage aligned with what users actually install.
3. Preserve provider boundaries so upstream sources can be changed without rewriting the MCP layer.
4. Harden and operate the existing stateless Streamable HTTP transport while preserving local stdio operation.
5. Refine the existing smaller hosted tool surface for ChatGPT/Codex against real deployment and buyer evidence.
6. Complete provider authorization and integrate the hosted service with the DigestSEO application and operational stack.
7. Package and test the hosted MCP as an OpenAI plugin only after the managed service is production-ready.

License

MIT. See LICENSE.