How to Run the MediaCrawler WebUI for Non-Command-Line Usage

Launch MediaCrawler's graphical interface by running the FastAPI backend and Vite frontend in development mode, or build static assets for a single-process production deployment.

MediaCrawler provides a WebUI interface that eliminates the need for terminal commands when configuring and monitoring crawling jobs. Built on a FastAPI backend and Vite-powered frontend, this browser-based dashboard lets you set parameters, track progress, and export results through interactive forms. According to the NanmiCoder/MediaCrawler source code, the WebUI supports two distinct running modes tailored to different deployment scenarios.

Prerequisites for Running the WebUI

Before starting the graphical interface, verify these dependencies:

• uv – the recommended Python package manager for dependency resolution
• Node.js (≥ 16) – required for the Vite development server and static builds
• Playwright browsers (optional) – only needed if you disable CDP mode

Install and verify uv:

uv --version   # should show a version number

Install browser drivers if needed:

uv run playwright install

Clone the repository and sync Python dependencies:

git clone https://github.com/NanmiCoder/MediaCrawler.git
cd MediaCrawler
uv sync

Development Mode: Interactive WebUI with Hot Reloading

Development mode runs the API server and Vite dev server as separate processes. This provides instant code reloading and is ideal for exploring features or customizing the interface.

Start the FastAPI Backend

In api/main.py, the FastAPI application registers routers for crawler operations, data retrieval, and WebSocket connections. Launch the backend on port 8080:

# Terminal 1

uv run uvicorn api.main:app --port 8080 --reload

The --reload flag enables automatic restart when Python files change. The API server exposes endpoints at http://localhost:8080/api/.

Start the Vite Frontend Dev Server

The frontend source lives in webui/ and proxies API requests to the backend. Open a second terminal:

# Terminal 2

cd webui
npm install
npm run dev

By default, the dev server serves the WebUI at http://localhost:5173 and forwards /api calls to port 8080.

Access the WebUI Interface

Open http://localhost:5173 in your browser. The dashboard automatically connects to the backend and displays:

• Platform selection (Xiaohongshu, Bilibili, etc.)
• Login type configuration (QR code, phone)
• Crawler type and keyword input
• Real-time progress monitoring via WebSocket

Production Mode: Single-Process WebUI Deployment

Production mode bundles the frontend into static assets served directly by the FastAPI process. No Node.js runtime is required for operation.

Build Static Frontend Assets

Execute the build command once to compile the Vite project:

cd webui
npm install
npm run build

Output is written to api/webui/, as configured in the build pipeline (documented in README lines 98–104).

Run the Unified API Server

Start only the FastAPI backend—it automatically detects and mounts the built assets:

uv run uvicorn api.main:app --port 8080

In api/main.py (lines 91–102), the static file mounting logic checks for WEBUI_DIR and registers routes for /assets, /logos, and /static. The compiled UI is served at the root path /.

Access http://localhost:8080 to use the WebUI without any separate frontend process.

Verifying Your WebUI Environment

Confirm that all dependencies are correctly installed by calling the environment check endpoint:

curl http://localhost:8080/api/env/check

A successful response returns "success": true. This endpoint, implemented in api/main.py (lines 88–130), executes uv run main.py --help to validate the crawling engine's availability.

Architecture of the MediaCrawler WebUI

Component	Path	Function
FastAPI backend	api/main.py	HTTP server, router registration, static file serving
Crawler router	api/routers/crawler.py	Handles /api/crawler/* endpoints for job submission
WebUI source	webui/	Vite + Vue/React frontend code
Crawling engine	main.py (project root)	CLI entry point invoked by API routes
Configuration	config/base_config.py	Global toggles affecting UI-driven behavior

When you submit a crawl job through the WebUI, the frontend sends a POST request to /api/crawler/run:

POST /api/crawler/run
{
  "platform": "xhs",
  "login_type": "qrcode",
  "crawler_type": "search",
  "keyword": "AI",
  "save_option": "jsonl"
}

The backend translates this JSON into command-line arguments and executes main.py with the specified parameters.

One-Line Launch Commands

Background Development Mode

uv run uvicorn api.main:app --port 8080 --reload & \
  cd webui && npm install && npm run dev

Complete Production Deployment

cd webui && npm install && npm run build && \
  cd .. && uv run uvicorn api.main:app --port 8080

Key Differences Between WebUI Modes

Aspect	Development Mode	Production Mode
Processes	Two (API + Node dev server)	One (API only)
Access URL	http://localhost:5173	http://localhost:8080
Code changes	Instant hot reload	Requires rebuild
Deployment complexity	Higher	Lower
Best for	Exploration, customization	Stable operation, server deployment

Summary

• MediaCrawler's WebUI provides full graphical control over crawling operations without terminal interaction.
• Development mode (uv run uvicorn api.main:app --reload + npm run dev) offers the fastest feedback loop for interactive use.
• Production mode (npm run build then single API server) simplifies deployment by eliminating the Node dependency.
• The backend (api/main.py) serves both API endpoints and—when assets are built—static UI files.
• The frontend (webui/) communicates with /api routes that invoke the core crawling engine in main.py.

Frequently Asked Questions

Can I run the WebUI without installing Node.js permanently?

No for development mode—Node.js is required to run the Vite dev server. Yes for production mode—Node is only needed during the build step. After running npm run build, you can deploy using only Python and uv.

Why does the WebUI use port 5173 in development but 8080 in production?

The Vite dev server defaults to port 5173 with proxy configuration to reach the API at 8080. In production, the FastAPI server itself serves the UI at port 8080, consolidating access to a single endpoint.

How do I debug WebUI connectivity issues?

Check three layers: (1) Verify the API responds with curl http://localhost:8080/api/env/check, (2) confirm the frontend proxy configuration in webui/vite.config.js points to the correct backend port, and (3) inspect browser DevTools Network tab for failed /api requests.

Can I customize which platforms appear in the WebUI interface?

Platform options are populated from the API response and ultimately derive from the modules in main.py. To add or remove platforms, modify the crawler registration logic in api/routers/crawler.py and ensure corresponding platform handlers exist in the crawling engine.

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