Trend Pulse

trend-pulse

[](https://github.com/claude-world/trend-pulse/actions/workflows/ci.yml) [](https://pypi.org/project/trend-pulse/) [](https://pypi.org/project/trend-pulse/) [](LICENSE)

Agentic Trend Intelligence Platform — 37 sources, plugin system, vector search, lifecycle prediction, 6-agent content factory, web dashboard, and 29-tool MCP server.

Use as a Python library, CLI tool, MCP server for Claude Code / AI agents, or a standalone web dashboard.

One-line MCP setup (zero install):

{ "mcpServers": { "trend-pulse": { "command": "uvx", "args": ["--from", "trend-pulse[mcp]", "trend-pulse-server"], "type": "stdio" } } }

> Paste into .mcp.json and you're done. Requires uv (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).

Sources

Built-in Sources (20)

All built-in sources are free and require zero authentication:

| Source | Data | Freshness | What you get | |--------|------|-----------|-------------| | Google Trends | RSS feed | Real-time | Trending searches by country + related news | | Hacker News | Firebase + Algolia | Real-time | Top stories with points, comments, search | | Mastodon | Public API | Real-time | Trending hashtags + trending links | | Bluesky | AT Protocol | Real-time | Trending topics + post search | | Wikipedia | Pageviews API | Daily | Most viewed pages by language/country | | GitHub | Trending page | Daily | Trending repos with stars, language | | PyPI | pypistats.org | Daily | Package download trends + growth signals | | Google News | RSS feed | Real-time | Top news stories by country | | Lobste.rs | JSON API | Real-time | Community-driven tech news | | dev.to | Public API | Daily | Developer community articles | | npm | Downloads API | Daily | JavaScript package download trends | | Reddit | Public JSON | Real-time | Popular posts across all subreddits | | CoinGecko | Public API | Real-time | Trending cryptocurrencies | | Docker Hub | Public API | Daily | Popular container images | | Stack Overflow | Public API | Real-time | Hot questions | | ArXiv | RSS/API | Daily | Trending research papers | | Product Hunt | Public API | Daily | Product launches and upvotes | | Lemmy | Public API | Real-time | Federated community posts (lemmy.world) | | Dcard | Public API | Real-time | Taiwan social platform trending posts | | PTT | Web scrape | Real-time | Taiwan BBS hot articles (Gossiping, Tech_Job, etc.) |

Plugin Sources (17)

Plugin sources live in src/trend_pulse/plugins/sources/ and are auto-discovered at startup:

| Source | ID | Category | What you get | |--------|----|----------|-------------| | Weibo | weibo | tw | China hot search list | | YouTube Trending | youtube_trending | global | Trending videos with view counts | | Threads | threads | social | Trending Threads posts | | X/Twitter | x_trending | social | Trending topics (optional bearer token) | | TikTok Trending | tiktok_trending | social | TikTok trending videos | | LINE Today TW | line_today | tw | Taiwan LINE Today news | | Mobile01 | mobile01 | tw | Taiwan tech community | | Bahamut | bahamut | tw | Taiwan gaming community | | ETtoday | ettoday | tw | Taiwan news | | Yahoo TW | yahoo_tw | tw | Yahoo Taiwan trending | | UDN | udn | tw | Taiwan UDN news | | CoinMarketCap | coinmarketcap | crypto | Trending cryptocurrencies | | DexScreener | dexscreener | crypto | DeFi/DEX trending tokens | | Pinterest | pinterest | social | Trending pins | | LinkedIn Trending | linkedin_trending | professional | LinkedIn trending topics | | Indie Hackers | indie_hackers | dev | Indie maker community | | Xiaohongshu | xiaohongshu | social | Chinese lifestyle platform |

Install

Zero-install with uvx (recommended)

uvx runs Python packages directly — no install, no venv, no setup:

# Run the CLI instantly
uvx trend-pulse trending

# Run the MCP server
uvx --from "trend-pulse[mcp]" trend-pulse-server

> uvx is the Python equivalent of npx. It comes with uv — install uv with curl -LsSf https://astral.sh/uv/install.sh | sh

pip install

pip install trend-pulse                  # core (httpx + aiosqlite)
pip install "trend-pulse[mcp]"           # MCP server
pip install "trend-pulse[dashboard]"     # Streamlit + FastAPI
pip install "trend-pulse[llm]"           # Claude API for hybrid scoring
pip install "trend-pulse[all]"           # everything

Quick Start

CLI

# What's trending right now? (all 37 sources, merged ranking)
trend-pulse trending

# Taiwan trends from Google + Hacker News
trend-pulse trending --sources google_trends,hackernews --geo TW

# Fetch + save snapshot to history DB
trend-pulse trending --save --count 10

# Take a full snapshot (all sources, auto-saves)
trend-pulse snapshot

# Query historical trends for a keyword
trend-pulse history "Claude" --days 7

# Search across sources
trend-pulse search "AI agent"

# List available sources (built-in + plugins)
trend-pulse sources

Python

import asyncio
from trend_pulse.aggregator import TrendAggregator

async def main():
    agg = TrendAggregator()

    # All sources, merged ranking
    result = await agg.trending(geo="TW", count=10)
    for item in result["merged_top"]:
        print(f"[{item['source']}] {item['keyword']} ({item.get('traffic', '')})")

    # With snapshot saving + velocity enrichment
    result = await agg.trending(count=5, save=True)
    for item in result["merged_top"]:
        print(f"{item['keyword']} — {item['direction']} (velocity: {item['velocity']})")

    # Query history
    history = await agg.history("Claude", days=7)
    for record in history["records"]:
        print(f"  {record['timestamp']}: score={record['score']}")

    # Search
    result = await agg.search("Claude AI")
    for item in result["merged_top"][:5]:
        print(f"{item['keyword']} - {item['score']:.0f}")

asyncio.run(main())

Single Source

import asyncio
from trend_pulse.sources import HackerNewsSource

async def main():
    hn = HackerNewsSource()
    items = await hn.fetch_trending(count=5)
    for item in items:
        print(f"{item.keyword} ({item.traffic})")

    # HN also supports search
    results = await hn.search("Python")
    for item in results[:3]:
        print(f"  {item.keyword}")

asyncio.run(main())

Phase 1–3 Intelligence APIs

# Lifecycle prediction
from trend_pulse.core.intelligence.lifecycle import predict_lifecycle, LifecycleStage
stage = predict_lifecycle(current_score=75, history=[{"score": s} for s in [20, 35, 50, 65]])
# -> LifecycleStage.EMERGING

# Trend clustering
from trend_pulse.core.intelligence.clusters import cluster_trends
clusters = await cluster_trends(items, threshold=0.25)

# 6-agent content workflow
from trend_pulse.core.agents.workflow import run_content_workflow
state = await run_content_workflow(
    trends=items,
    platforms=["threads", "x"],
    brand_voice="casual",
    topic="AI tools",
)
content = state["final_content"]  # {"threads": "...", "x": "..."}

# Hybrid scoring (heuristic + optional Claude API)
from trend_pulse.core.scoring.hybrid import score_content
result = await score_content("Your post content", "threads")
print(result.total, result.grade, result.mode)  # 78.5, B+, heuristic

# Vector similarity search
from trend_pulse.core.vector.simple import SimpleVectorStore
store = SimpleVectorStore()
await store.upsert(items)
similar = await store.search_similar("artificial intelligence", k=5)

MCP Server (for Claude Code / AI agents)

Step 1: Install uv (if you don't have it)

# macOS
brew install uv

# Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Add to .mcp.json

Create or edit .mcp.json in your project root (or ~/.claude/.mcp.json for global):

{
  "mcpServers": {
    "trend-pulse": {
      "command": "uvx",
      "args": ["--from", "trend-pulse[mcp]", "trend-pulse-server"],
      "type": "stdio"
    }
  }
}

That's it. No pip install, no venv, no Python version management. uvx downloads and caches the package automatically on first run.

Step 3 (optional): Enable browser rendering

The render_page tool uses Cloudflare Browser Rendering to fetch JS-heavy pages. If you want this feature, add your Cloudflare credentials:

{
  "mcpServers": {
    "trend-pulse": {
      "command": "uvx",
      "args": ["--from", "trend-pulse[mcp]", "trend-pulse-server"],
      "type": "stdio",
      "env": {
        "CF_ACCOUNT_ID": "your-cloudflare-account-id",
        "CF_API_TOKEN": "your-cloudflare-api-token"
      }
    }
  }
}

> Get these from Cloudflare Dashboard → Workers & Pages → Overview. Skip this step if you don't need it — all other 28 tools work without any credentials.

Alternative: pip install

If you prefer a traditional install instead of uvx:

pip install "trend-pulse[mcp]"

{
  "mcpServers": {
    "trend-pulse": {
      "command": "trend-pulse-server",
      "type": "stdio"
    }
  }
}

Available tools (29)

Trend Data (5):

| Tool | Description | |------|-------------| | get_trending | Fetch trending topics (all or selected sources, with optional --save) | | search_trends | Search across sources by keyword | | list_sources | List built-in sources and their properties | | get_trend_history | Query historical trend data for a keyword | | take_snapshot | Fetch + save snapshot to history DB |

Intelligence (5):

| Tool | Description | |------|-------------| | search_semantic | Vector similarity search across indexed trends | | get_trend_clusters | Cluster related trends by semantic similarity | | get_lifecycle_prediction | Predict lifecycle stage for a trend (EMERGING / PEAK / DECLINING / FADING) | | list_sources_extended | List all sources including plugins, with category and frequency metadata | | get_trend_velocity | Get velocity and direction signals for a keyword |

Content Guides (5):

All content guide tools return structured guides — the LLM does all judgment and creative work.

| Tool | Description | |------|-------------| | get_content_brief | Writing brief: hook examples, patent strategies, scoring dimensions, CTA examples | | get_scoring_guide | 5-dimension scoring framework + 4 Threads algorithm penalty pre-checks | | get_platform_specs | Platform specs: char limits, Threads creator insights, algo priority, best times | | get_review_checklist | 15-item review checklist (7 critical / 5 warning / 3 info) with severity and fix methods | | get_reel_guide | Reel/Short video guide: scene structure, timing, visual guidance, editing tips |

Agentic Content (8):

| Tool | Description | |------|-------------| | run_content_workflow | Run the 6-agent content factory end-to-end for one or more platforms | | get_ab_variants | Generate A/B variants of a post for testing | | get_campaign_calendar | Build a content calendar from a list of trends | | score_content_hybrid | Score content using heuristic + optional Claude API judge | | adapt_content | Adapt a post from one platform's format to another | | generate_hashtags | Generate platform-optimized hashtag sets for a topic | | analyze_viral_factors | Analyze a post for viral potential signals | | batch_score_content | Score multiple posts in a single call |

Operations (5):

| Tool | Description | |------|-------------| | get_trend_report | Generate a formatted trend report for a time window | | compare_trends | Compare two or more keywords across sources and time | | get_source_status | Health-check all sources and return availability status | | send_notification | Send a trend alert via configured notification channel | | export_data | Export trend history to CSV or JSON |

Browser (1, optional — requires Cloudflare credentials):

| Tool | Description | |------|-------------| | render_page | Render JS-heavy pages via Cloudflare Browser Rendering (SSRF-guarded) |

Dashboard & REST API

# Start Streamlit dashboard
streamlit run src/trend_pulse/dashboard/app.py

# Start FastAPI REST API
uvicorn trend_pulse.dashboard.api:app --port 8000

# Docker Compose (all services)
docker compose up

Docker Compose services:

| Service | Description | Port | |---------|-------------|------| | api | FastAPI + MCP server | 8000 | | worker | Background trend fetcher | — | | dashboard | Streamlit UI | 8501 |

Notifications

from trend_pulse.notifications.channels import DiscordWebhook
notifier = DiscordWebhook(webhook_url="https://discord.com/api/webhooks/...")
await notifier.send("Trending now", {"keyword": "Claude AI", "score": 95})

CLI Reference

trend-pulse trending [--sources SRC] [--geo CODE] [--count N] [--save]
trend-pulse search QUERY [--sources SRC] [--geo CODE]
trend-pulse history KEYWORD [--days N] [--source SRC]
trend-pulse snapshot [--sources SRC] [--geo CODE] [--count N]
trend-pulse sources

--sources: Comma-separated source IDs.

Built-in: google_trends, hackernews, mastodon, bluesky, wikipedia, github, pypi, google_news, lobsters, devto, npm, reddit, coingecko, dockerhub, stackoverflow, arxiv, producthunt, lemmy, dcard, ptt

Plugins: weibo, youtube_trending, threads, x_trending, tiktok_trending, line_today, mobile01, bahamut, ettoday, yahoo_tw, udn, coinmarketcap, dexscreener, pinterest, linkedin_trending, indie_hackers, xiaohongshu

--geo: ISO country code (e.g., TW, US, JP, DE).

• Google Trends / Google News: filters by country
• Wikipedia: selects language edition
• GitHub: treated as language filter (e.g., python)
• Other sources: ignored (global data)

--save: Save results to local SQLite DB (~/.trend-pulse/history.db) for velocity tracking.

Plugin System

Drop a file into src/trend_pulse/plugins/sources/ — no registration needed. The PluginRegistry auto-discovers all modules that export a register() function.

from trend_pulse.plugins.base import PluginSource
from trend_pulse.sources.base import TrendItem

class MyPluginSource(PluginSource):
    name = "my_plugin"
    description = "My custom plugin source"
    category = "global"   # global, tw, dev, crypto, social, professional
    frequency = "daily"

    async def fetch_trending(self, geo="", count=20) -> list[TrendItem]:
        return [TrendItem(keyword="...", score=80.0, source=self.name)]

def register():
    return MyPluginSource()

Plugin categories: global, tw, dev, crypto, social, professional

For the legacy TrendSource interface (built-in sources), see [docs/custom-sources.md](docs/custom-sources.md) and [examples/customrsssource.py](examples/customrsssource.py).

Velocity & Direction

When history data is available, each trend item includes:

{
  "keyword": "Claude AI",
  "score": 92,
  "direction": "rising",
  "velocity": 15.3,
  "previous_score": 45.0,
  "source": "hackernews"
}

| Direction | Meaning | |-----------|---------| | rising | Velocity > 10 (score increasing rapidly) | | stable | Velocity between -10 and 10 | | declining | Velocity LifecycleStage.EMERGING

## History Database

Snapshots are stored in SQLite at `~/.trend-pulse/history.db` (override with `TREND_PULSE_DB` env var).

```bash
# Save snapshots over time
trend-pulse trending --save --count 5
# ... wait some time ...
trend-pulse trending --save --count 5

# Query history
trend-pulse history "Claude" --days 7
trend-pulse history "React" --days 30 --source npm

Output Format

All commands r

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: claude-world
• Source: claude-world/trend-pulse
• License: MIT

Install and usage instructions live in the source repository linked above.