# How to Install TrendRadar: A Complete Guide for Local, Docker, and MCP Server Setup

> Install TrendRadar easily with our comprehensive guide. Learn local installers, Docker Compose, or manual Python setup on Windows, macOS, Linux, and MCP server.

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

---

**You can install TrendRadar via three methods: one-click local installers for Windows/macOS/Linux using `uv`, Docker Compose for containerized deployment, or manual Python setup with the FastMCP server.**

TrendRadar is a Python-based news aggregation and AI analysis tool that requires careful environment setup to run its crawler, web UI, and MCP server components. This guide covers every installation method with exact commands from the [sansan0/TrendRadar](https://github.com/sansan0/TrendRadar) repository.

## Prerequisites for Installing TrendRadar

Before running any installer, verify your system meets these requirements.

| Operating System | Required Tools |
|------------------|--------------|
| **Windows** | Python 3.10+ (from [python.org](https://www.python.org/downloads/)), `uv` (auto-installed if missing) |
| **macOS / Linux** | Python 3.10+, `uv` (auto-installed if missing) |
| **Docker** | Docker Engine + Docker Compose (or Docker Desktop) |

The `uv` package manager is critical for TrendRadar installation. Both `setup-windows.bat` and [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) will attempt automatic installation if `uv` is not found on your system.

## Method 1: Local Installation on Windows

The Windows installer provides one-click setup with automatic dependency resolution.

### Step 1: Clone and Launch

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

```

Double-click `setup-windows.bat` or run from Command Prompt:

```bat
setup-windows.bat

```

### Step 2: What the Script Does

The `setup-windows.bat` script in the repository root performs these validation steps:

- Verifies execution in project root by checking for [`pyproject.toml`](https://github.com/sansan0/TrendRadar/blob/main/pyproject.toml)
- Detects Python ≥ 3.10 and reports the version
- Installs `uv` automatically via PowerShell or `pip` if missing
- Runs `uv sync` to create virtual environment and install dependencies
- Validates [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) exists or creates it from example

### Step 3: Start the MCP Server

After installation, the script outputs the MCP configuration for Cherry Studio:

```bat
uv run python -m mcp_server.server

```

This starts the FastMCP server on `127.0.0.1:3333` by default.

## Method 2: Local Installation on macOS and Linux

Unix systems use an equivalent Bash installer with identical functionality.

### Run the Installer

```bash
chmod +x setup-mac.sh
./setup-mac.sh

```

The [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) script mirrors the Windows logic:

- Detects or installs `uv` via the official installer script
- Executes `uv sync` for dependency management
- Checks [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) and prompts to copy the example if needed

### Start the Server

```bash
uv run python -m mcp_server.server

```

The MCP command output for Cherry Studio is identical to Windows.

## Method 3: Docker Installation (Recommended for Servers)

Docker provides the most reliable TrendRadar installation for production deployments and NAS environments.

### Step 1: Prepare Configuration

Create a `config/` directory and copy the example configuration:

```bash
mkdir -p config output
cp config/config.example.yaml config/config.yaml

# Edit config.yaml with your notification secrets

```

### Step 2: Pull and Start

```bash
cd docker
docker compose up -d

```

The [`docker/docker-compose.yml`](https://github.com/sansan0/TrendRadar/blob/main/docker/docker-compose.yml) in the repository:

- Mounts `../config` → `/app/config` (read-only)
- Mounts `../output` → `/app/output` for persistent storage
- Exposes web UI on `127.0.0.1:${WEBSERVER_PORT:-8080}`
- Runs the MCP server in a separate `trendradar-mcp` service on port 3333

### View Logs

```bash
docker compose logs -f

```

## Post-Installation: Configure Notification Secrets

TrendRadar requires environment variables for all notification channels. These match GitHub Actions secrets format.

Required variables (from [`README-EN.md`](https://github.com/sansan0/TrendRadar/blob/main/README-EN.md) in the repository):

| Service | Variable Names |
|---------|--------------|
| WeWork | `WEWORK_WEBHOOK_URL`, `WEWORK_MSG_TYPE` |
| Feishu | `FEISHU_WEBHOOK_URL` |
| Slack | `SLACK_WEBHOOK_URL` |
| ntfy | `NTFY_SERVER_URL`, `NTFY_TOPIC`, `NTFY_TOKEN` |
| Bark | `BARK_URL` |
| Email | `EMAIL_*` variables for SMTP configuration |

Add these via GitHub repository **Settings → Secrets and variables → Actions**, or create a `.env` file for Docker Compose.

## Verify Your TrendRadar Installation

Run the built-in version check to confirm proper installation:

```bash
python -m trendradar --check-version

```

This command from [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) contacts the upstream version endpoint, compares with local `__version__`, and validates [`config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config.yaml) and [`timeline.yaml`](https://github.com/sansan0/TrendRadar/blob/main/timeline.yaml) versions.

Expected output on success:

```

✅ 已是最新
✅ config.yaml: 1.0.0 ✅
✅ timeline.yaml: 1.0.0 ✅

```

## Troubleshooting Common Installation Issues

| Issue | Solution |
|-------|----------|
| `uv` not found | Run the installer script again; it attempts automatic installation |
| [`config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config.yaml) missing | Copy from [`config/config.example.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.example.yaml) and fill in your secrets |
| Port 3333 already in use | Stop existing MCP server or modify the port in configuration |
| Docker volume permission errors | Ensure `output/` directory exists and is writable by UID 1000 |

## Summary

- **Local installation** uses `setup-windows.bat` or [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) to automate Python environment setup with `uv`
- **Docker deployment** provides the most reliable production installation via `docker compose up -d` in the `docker/` directory
- **MCP server** starts with `uv run python -m mcp_server.server` on all platforms
- **Configuration** requires copying [`config/config.example.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.example.yaml) and adding notification secrets as environment variables
- **Verification** uses `python -m trendradar --check-version` to confirm successful installation

## Frequently Asked Questions

### What is the fastest way to install TrendRadar?

The fastest method is running the one-click installer for your operating system: `setup-windows.bat` for Windows or [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) for macOS and Linux. Both scripts automatically install the `uv` package manager, create a virtual environment, and install all dependencies.

### Does TrendRadar require Python to be pre-installed?

Yes, Python 3.10 or higher must be installed before running the installers. The scripts will verify your Python version and fail with a clear message if the requirement is not met. Download Python from [python.org](https://www.python.org/downloads/) if needed.

### How do I install TrendRadar on a NAS or headless server?

Use the Docker installation method. The [`docker/docker-compose.yml`](https://github.com/sansan0/TrendRadar/blob/main/docker/docker-compose.yml) file is designed for server deployments, mounting configuration and output directories as persistent volumes. This avoids Python environment management entirely and runs reliably on ARM64 and AMD64 architectures.

### What environment variables does TrendRadar need after installation?

TrendRadar requires webhook URLs and API tokens for your chosen notification channels. Common variables include `WEWORK_WEBHOOK_URL` for WeWork, `FEISHU_WEBHOOK_URL` for Feishu, `SLACK_WEBHOOK_URL` for Slack, and `EMAIL_*` variables for SMTP. The full list is documented in [`README-EN.md`](https://github.com/sansan0/TrendRadar/blob/main/README-EN.md).