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

> Easily set up TrendRadar by cloning the repo, installing dependencies, configuring settings, and running the aggregator. Follow our complete installation guide.

- Repository: [sansan/TrendRadar](https://github.com/sansan0/TrendRadar)
- Tags: getting-started
- Published: 2026-04-22

---

**To set up TrendRadar, clone the repository, install UV, configure [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/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](https://github.com/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/main/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/main/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/main/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/main/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/main/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

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

```

### Step 2: Install UV

```bash
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/main/setup-mac.sh)](https://github.com/sansan0/TrendRadar/blob/master/setup-mac.sh)
- **Windows**: [`setup-windows.bat`](https://github.com/sansan0/TrendRadar/blob/master/setup-windows.bat)

### Step 3: Sync Dependencies

```bash
uv sync

```

This creates a reproducible virtual environment using the exact versions from [`uv.lock`](https://github.com/sansan0/TrendRadar/blob/master/uv.lock).

### Step 4: Configure Your Settings

Copy and edit the main configuration file:

```bash
cp config/config.yaml config/config.yaml.local

```

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

```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:

```bash
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

```bash
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/main/docker/docker-compose.yml)](https://github.com/sansan0/TrendRadar/blob/master/docker/docker-compose.yml) orchestrates both the main application and optional MCP server:

```bash

# 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:

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

```

The [`docker/Dockerfile`](https://github.com/sansan0/TrendRadar/blob/master/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/main/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/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config.yaml):

```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:

```yaml
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:

```yaml
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:

```bash
./start-http.sh

```

Or manually:

```bash
python -m http.server 8080 --directory output

```

Then open `http://localhost:8080` to view [[`output/index.html`](https://github.com/sansan0/TrendRadar/blob/main/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:

```bash
uv venv --python 3.11
uv sync

```

### Scheduler Not Running

Check [[`trendradar/core/scheduler.py`](https://github.com/sansan0/TrendRadar/blob/main/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/main/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/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/output/index.html) for browser-based viewing. You can enable additional HTML/TXT snapshots via the storage configuration in [`config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config.yaml).