How to Set Up TrendRadar: Complete Installation Guide for the Hot-Topic Aggregator

To set up TrendRadar, clone the repository, install UV, configure config/config.yaml, add your notification secrets, and run uv run -m trendradar or deploy via Docker.

TrendRadar is a lightweight, pluggable hot-topic aggregator that pulls data from dozens of Chinese and international hot-search platforms. This guide walks you through the complete TrendRadar setup process using official source files from the sansan0/TrendRadar repository.

Understanding TrendRadar's Architecture

Before diving into installation, understanding the core components helps you configure the system correctly.

Key Components

Component	Role	Source File
Configuration	Centralized YAML config defining data sources, schedule, and channels	[config/config.yaml](https://github.com/sansan0/TrendRadar/blob/master/config/config.yaml)
Config Loader	Parses and validates YAML, provides typed config object	[trendradar/core/config.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/core/config.py)
Scheduler	Implements timeline system for crawl/push timing	[trendradar/core/scheduler.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/core/scheduler.py)
Crawler/Loader	Retrieves hot-list data, stores in SQLite	[trendradar/core/loader.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/core/loader.py)
AI Analysis (MCP)	FastAPI-style server for AI-driven analysis	[mcp_server/server.py](https://github.com/sansan0/TrendRadar/blob/master/mcp_server/server.py)

Prerequisites for TrendRadar Setup

Before installing, ensure you have:

• Python 3.10+ (the project uses modern Python features)
• UV package manager (recommended for reproducible environments)
• Git for cloning the repository
• Docker (optional, for containerized deployment)

Installation Method 1: Local Setup with UV

The fastest way to set up TrendRadar locally uses the UV package manager for dependency management.

Step 1: Clone the Repository

git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar

Step 2: Install UV

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

Or use the platform-specific scripts provided in the repository:

• macOS: [setup-mac.sh](https://github.com/sansan0/TrendRadar/blob/master/setup-mac.sh)
• Windows: setup-windows.bat

Step 3: Sync Dependencies

uv sync

This creates a reproducible virtual environment using the exact versions from uv.lock.

Step 4: Configure Your Settings

Copy and edit the main configuration file:

cp config/config.yaml config/config.yaml.local

Edit at minimum these fields in [config/config.yaml](https://github.com/sansan0/TrendRadar/blob/master/config/config.yaml):

app:
  timezone: "Asia/Shanghai"  # Adjust to your timezone

schedule:
  preset: "morning_evening"  # Or "hourly", "realtime", etc.

Step 5: Set Environment Secrets

For notification channels, export the required secrets:

export FEISHU_WEBHOOK_URL="https://open.feishu.cn/..."
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"

See the README's "GitHub Secrets" table for the complete list of supported environment variables.

Step 6: Run TrendRadar

uv run -m trendradar

The crawler executes based on your schedule preset, storing data in output/ and sending notifications through configured channels.

Installation Method 2: Docker Deployment

For production TrendRadar setup, Docker provides the most reliable deployment.

Using Docker Compose

The [docker/docker-compose.yml](https://github.com/sansan0/TrendRadar/blob/master/docker/docker-compose.yml) orchestrates both the main application and optional MCP server:

# Build and start

docker compose up -d

# View logs

docker logs -f trendradar

# Restart with AI enabled

docker restart trendradar-mcp

Environment Configuration

Create a .env file in the project root:

FEISHU_WEBHOOK_URL=https://open.feishu.cn/...
TELEGRAM_BOT_TOKEN=your-token
AI_API_KEY=your-openai-key

The docker/Dockerfile handles UV installation, dependency sync, and sets python -m trendradar as the entrypoint.

Installation Method 3: Cherry Studio MCP Integration

For personal use with AI assistants, set up TrendRadar as an MCP server in Cherry Studio.

After running [setup-mac.sh](https://github.com/sansan0/TrendRadar/blob/master/setup-mac.sh), the script outputs the exact configuration:

名称: TrendRadar
描述: 新闻热点聚合工具
类型: STDIO
命令: /home/youruser/.cargo/bin/uv
参数:
  --directory
  /path/to/TrendRadar
  run
  python
  -m
  mcp_server.server

Paste this into Cherry Studio's MCP settings, enable the toggle, and the AI assistant can now query trending topics through the MCP interface.

Configuring Advanced Features

Customizing the Ranking Algorithm

The [trendradar/core/frequency.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/core/frequency.py) implements a weighted scoring formula. Adjust weights in config.yaml:

advanced:
  weight:
    rank: 0.6
    frequency: 0.3
    hotness: 0.1

Enabling AI-Powered Filtering

For AI-driven content filtering instead of keyword-based:

filter:
  method: "ai"  # vs "keyword"

  frequency_words: "config/frequency_words.txt"

ai:
  enabled: true
  model: "openai/gpt-4o"
  temperature: 0.7

Start the MCP server: uv run -m mcp_server.server

Adding Custom Notification Channels

To add Slack support, set SLACK_WEBHOOK_URL and configure:

notification:
  enabled: true
  channels:
    slack:
      webhook_url: "${SLACK_WEBHOOK_URL}"

The internal batch_size for Slack can be tuned under advanced.batch_size.slack.

Viewing Results

Local HTML Report

Start the built-in HTTP server:

./start-http.sh

Or manually:

python -m http.server 8080 --directory output

Then open http://localhost:8080 to view [output/index.html](https://github.com/sansan0/TrendRadar/blob/master/index.html) with dark-mode support and keyword-grouped tabs.

GitHub Pages Deployment

The generated HTML can be deployed to GitHub Pages for public access. The repository includes configuration for automated deployment via GitHub Actions.

Troubleshooting Common Setup Issues

UV Installation Failures

If uv sync fails, ensure you have Python 3.10+ and try:

uv venv --python 3.11
uv sync

Scheduler Not Running

Check [trendradar/core/scheduler.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/core/scheduler.py) logs. The timeline system requires valid schedule.preset values: morning_evening, hourly, realtime, or custom timeline definitions.

Notification Delivery Failures

Verify environment variables are exported (not just in .env files for non-Docker runs). Each channel has specific format requirements implemented in [trendradar/__main__.py](https://github.com/sansan0/TrendRadar/blob/master/trendradar/__main__.py).

MCP Server Connection Errors

Ensure the MCP server is running before starting the main application when ai.enabled: true. The server exposes tools via STDIO or HTTP depending on configuration in [mcp_server/server.py](https://github.com/sansan0/TrendRadar/blob/master/mcp_server/server.py).

Summary

• TrendRadar setup requires Python 3.10+, UV package manager, and a configured config/config.yaml
• Three deployment paths: Local UV (development), Docker (production), or Cherry Studio MCP (AI integration)
• Core configuration: Set timezone, schedule preset, notification channels, and optional AI filtering
• Environment secrets: Export webhook URLs and API keys before running
• Verification: Run uv run -m trendradar locally or docker compose up -d for containerized deployment

Frequently Asked Questions

What is the minimum configuration needed to run TrendRadar?

At minimum, you need to set app.timezone to your local timezone, choose a schedule.preset (such as morning_evening or hourly), and enable at least one notification channel in config/config.yaml. No AI or advanced features are required for basic operation.

Can I run TrendRadar without Docker?

Yes. The recommended local method uses UV package manager: run uv sync to install dependencies, then uv run -m trendradar to execute. Platform-specific scripts setup-mac.sh and setup-windows.bat automate this process.

How do I enable AI-powered content analysis?

Set ai.enabled: true in config.yaml, configure your AI model (default: openai/gpt-4o), and start the MCP server with uv run -m mcp_server.server. You can then set filter.method: "ai" to use AI-driven filtering instead of keyword-based filtering.

Where does TrendRadar store its data?

By default, raw crawled data is stored in SQLite databases under output/, with platform-specific .db files. The system also generates output/index.html for browser-based viewing. You can enable additional HTML/TXT snapshots via the storage configuration in config.yaml.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}