news-agent

News Agent is a local, personal news service. It collects RSS feeds, Hacker News, and built-in signal sources into one scored news pool, adds a GitHub Trending digest, and uses an OpenAI-compatible LLM to rank, summarize, and deliver to Feishu or Discord.

It runs on macOS, Windows, and Linux. A local web console, HTTP API, and stdio MCP server all manage the same configuration and jobs.

Features

• Aggregate RSS feeds, Hacker News, Product Hunt, Reddit, App Store new apps, V2EX, 36Kr, Sspai, OSChina, Jike topics, and other built-in sources into one news pool, with GitHub Trending generated alongside it.
• Rank, filter, deduplicate, and summarize content with an LLM.
• Add, update, verify, and remove RSS sources from the web console, API, or MCP.
• Set interests, exclusions, source weights, delivery times, and item limits.
• Run scheduled fetches and deliveries, or trigger them manually.
• Deliver to Feishu, Discord, or a custom HTTP endpoint.
• Keep configuration, logs, and job history in the local user-data directory.
• Bind the local control plane to 127.0.0.1:12301 by default.

Requirements

• macOS, Windows, or Linux
• uv
• An API key for an OpenAI Chat, OpenAI Responses, or Anthropic Messages endpoint

The installer scripts for macOS, Linux, and Windows will automatically install uv for the current user if it is not already available.

Install

You can install News Agent using a single terminal command without cloning first:

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/huawolf/news-agent/main/scripts/install.sh | bash

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/huawolf/news-agent/main/scripts/install.ps1 | iex

The installer creates .env from .env.example, installs the locked runtime dependencies, registers a per-user login service, and restarts that service so repeated installs immediately run the updated code. Open http://127.0.0.1:12301 after installation.

Configure

Default Client Mode

Regular users run in client mode by default. The shared server fetches and scores the common source catalog once; each client pulls the last 24 hours of processed entries scoring at least 60 plus the latest successful GitHub digest, adds and scores only its private custom RSS feeds, then uses its own preferences, schedule, language, item limit, LLM, and delivery channel to select, summarize, and send the digest.

The default connection is:

"mode_settings": {
  "mode": "client",
  "server_url": "http://13.158.182.33:12301",
  "server_api_token_name": "processednews"
}

processednews is the shared-news API value and does not protect the local configuration page. NEWS_AGENT_LOCAL_TOKEN is a separate, optional private password used only by the local Web/configuration API. Never replace one with the other.

The local page reads /api/news-sources under the optional local-control rule. Remote clients read /api/server/sources with processednews; these are separate endpoints so an unset NEWS_AGENT_LOCAL_TOKEN never causes the local page to request shared-news authentication.

Operators running the shared service use mix mode. Mix mode performs the server fetch/scoring work, retains a rolling 24-hour in-memory cache, exposes the shared-news endpoints, and can also run its own delivery workflow. Manual and scheduled runs both process the full enabled source set and GitHub; delivery schedules control only time and final news count. Configurations without mode_settings receive the same regular-user client defaults. Set standalone or mix explicitly only for self-hosted operation.

Configure the model, endpoint, protocol, API key, and delivery webhooks in the Model and delivery settings section of the local web console. The fields save automatically and the model connection can be tested in place. Keep the console private because it displays configured secret values.

Secrets are stored in .env. Model settings, preferences, and delivery schedules are stored in config.json through the validated local API. The LLM key variable in .env must match llm.apiKeyName; the default configuration uses DEEPSEEK_API_KEY.

DEEPSEEK_API_KEY=your_llm_api_key
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/...
# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

When using another key variable, such as OPENAI_API_KEY or ANTHROPIC_API_KEY, set llm.apiKeyName to the same name through the local API. After editing .env directly, restart the service from the project directory:

uv run news-agent service restart

The first service start creates config.json from config.json.example. Use the web console or local API to manage model settings, feeds, preferences, and schedules instead of replacing the active configuration file.

Optional source integrations can also use .env credentials. Product Hunt, for example, uses PH_TOKEN when configured and falls back to its public feed when the token is absent.

Important settings:

• preferences: interests, exclusions, source weights, language preference, and diversity limits.
• llm: model, endpoint, API-key environment variable, and protocol. The Web console detects OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages from the endpoint and model name, allows manual override, and can save and test the current connection.
• sections.signals: built-in signal adapters for Product Hunt, Reddit fallback, GitHub variants, V2EX, RSSHub topics, App Store regions, and domestic RSS sources.
• schedule.fetch_lookback_minutes: fetch lookback window; defaults to 1440 minutes so built-in signals only keep the last 24 hours, except daily ranking pages such as GitHub Trending.
• log.retention_days: number of daily log directories to retain; defaults to 30 days.
• delivery.schedules: cron schedules and the unified news max_items limit per delivery. Every run processes the full news source pool and GitHub; sources are not selected per schedule. Without an explicit schedule, deliveries default to 10:00 and 20:00 daily, with at most 10 news items each time.
• delivery.immediate: high-score alert threshold and daily limit.
• mode_settings: selects standalone, mix, or client. Client deployments read pre-scored entries with score >= 60 from server_url; mix deployments also expose the rolling shared-news API. server_api_token_name carries the shared API value processednews; it is unrelated to NEWS_AGENT_LOCAL_TOKEN.
• push: enable Feishu, Discord, or a custom endpoint.

Run

Use uv run news-agent for all commands:

uv sync                         # Install development dependencies
uv run news-agent check         # Check LLM connectivity
uv run news-agent fetch         # Fetch and score once
uv run news-agent push          # Generate and send one digest
uv run news-agent serve         # Run the local web/API service
uv run news-agent mcp           # Run the stdio MCP server
uv run news-agent service status

The serve command starts the built-in scheduler and the local API at http://127.0.0.1:12301. Interactive API documentation is available at http://127.0.0.1:12301/docs.

A shared mix server must listen on an interface reachable by its clients, for example:

uv run news-agent serve --host 0.0.0.0 --port 12301

Before exposing a mix server, set a private NEWS_AGENT_LOCAL_TOKEN for its management API. Clients still use processednews only for shared-news reads.

To remove the login service without deleting data:

./scripts/uninstall.sh

On Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1

Local API and MCP

The local API supports configuration, source, delivery, job, and log operations. Set NEWS_AGENT_LOCAL_TOKEN in .env to protect these local management requests. It is not the shared server value processednews and is never used for client-to-server news retrieval.

The MCP server is intended for a local agent process:

{
  "command": "uv",
  "args": ["run", "news-agent", "mcp"],
  "cwd": "/path/to/news-agent"
}

Available MCP tools include source management, preference and schedule updates, manual fetch/push jobs, digest previews, job status, and recent logs. run_push requires explicit confirmation.

AI agents performing installation or initial configuration should follow the News Agent Operator skill. It defines the non-browser workflow for secret handling, API configuration, service restart, health checks, model testing, previews, and confirmed delivery.

Data and Logs

Runtime data is stored in the project directory by default:

Type	Directory
News data	news-data/
Logs	logs/
Job records	runs/

Use NEWS_AGENT_DATA_DIR or NEWS_AGENT_CONFIG to override these paths. Application logs use rotating files; the project does not depend on system journals. Mix and standalone servers keep the latest successful GitHub section at news-data/github-latest.md; shared clients read it through /api/server/github-trending.

Security

News Agent binds to loopback by default. Regular clients should keep that default. A mix server may expose port 12301 for shared-news clients; protect its local management routes with NEWS_AGENT_LOCAL_TOKEN and restrict network access where practical. The public processednews value is not a management password. Keep .env, webhook URLs, and API keys out of version control.

Contributing

Issues and pull requests are welcome. Please keep changes focused, add tests for behavior changes, and update the relevant documentation when configuration or user-facing behavior changes.

License

This project is licensed under the MIT License.