Guide · Open source

How to use NewsNow: run it, self-host it and connect MCP

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

NewsNow is an open-source web app that gathers currently trending news from several sources and displays it in a simple, minimal reading layout. This guide explains how to read it, how to run your own copy from source, how to deploy it and how to connect it to an MCP-compatible AI client. By the end you will know which setup fits your needs and what the project does and does not cover.

NewsNownewsnext/newsnow · ★ 22.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Node.js 20 or newer. Enable pnpm with corepack, and install Docker only if you plan to use the Docker deployment.
2Clone the repository. Run git clone https://github.com/newsnext/newsnow to get the source code.
3Enable corepack and install. Run corepack enable, then pnpm i to install dependencies.
4Start the dev server. Run pnpm dev and open the local address it prints to read the trending news view.
5Configure optional settings. For login and caching, create .env.server from example.env.server and set the GitHub OAuth and database values.
6Deploy or connect an AI client. Deploy on Cloudflare Pages or Vercel, or add the MCP server config with your BASE_URL.

What NewsNow does

NewsNow shows what is trending in the news in a clean, uncluttered layout. It refreshes on a schedule and caches results, so pages load quickly and the underlying sources are not hit too often.

The project's features include real-time updates on trending news, a 30-minute default cache duration (logged-in users can force a refresh) and an adaptive scraping interval with a minimum of 2 minutes, based on how often each source updates.

Minimal reading interface focused on headlines
Trending news updated in near real time
Optional GitHub OAuth login with data synchronization
MCP server support

Run NewsNow locally from source

To run a development copy, clone the repository, enable corepack, install dependencies and start the development server. The README notes that this requires Node.js 20 or newer.

Corepack provides pnpm. Docker is only needed if you plan to use the Docker deployment.

Prerequisites: Node.js 20 or newer, pnpm (via corepack), and Docker only for the Docker deployment

git clone https://github.com/newsnext/newsnow
corepack enable
pnpm i
pnpm dev

Deploy your own copy

For a deployment without login and caching, the README suggests forking the repository and importing it into a platform such as Cloudflare Pages or Vercel.

For Cloudflare Pages, the build command is pnpm run build and the output directory is dist/output/public.

Docker users can run docker compose up from the project root. Environment variables can also be set in docker-compose.yml.

Basic deployment: fork the repo, then import it into Cloudflare Pages or Vercel
Cloudflare Pages build command: pnpm run build
Cloudflare Pages output directory: dist/output/public

docker compose up

Login and caching need environment variables. Copy or rename example.env.server to .env.server for local development. The README lists G_CLIENT_ID, G_CLIENT_SECRET, JWT_SECRET, INIT_TABLE and ENABLE_CACHE. INIT_TABLE must be set to true on the first run and can be turned off afterward.

For GitHub login, create a GitHub App, add no special permissions, set the callback URL to https://your-domain.com/api/oauth/github (replacing your-domain), then copy the Client ID and Client Secret.

The README recommends Cloudflare D1 as the database. Create a D1 database in the Cloudflare Worker dashboard, set database_id and database_name in wrangler.toml (rename example.wrangler.toml if wrangler.toml is missing), and redeploy. Other connectors are listed at https://db0.unjs.io/connectors.

G_CLIENT_ID and G_CLIENT_SECRET: GitHub app credentials
JWT_SECRET: usually the same as the client secret, per the README
INIT_TABLE=true on first run only
ENABLE_CACHE=true to turn on caching

G_CLIENT_ID=
G_CLIENT_SECRET=
JWT_SECRET=
INIT_TABLE=true
ENABLE_CACHE=true

Connect NewsNow to an MCP-compatible AI client

NewsNow includes an MCP server. The example configuration runs the npm package newsnow-mcp-server through npx and sets BASE_URL to the public NewsNow address. Change BASE_URL to your own domain if you host your own copy.

Add this to the configuration file of your MCP-compatible client.

Set BASE_URL to your own domain if self-hosting

{
  "mcpServers": {
    "newsnow": {
      "command": "npx",
      "args": ["-y", "newsnow-mcp-server"],
      "env": {
        "BASE_URL": "https://newsnow.busiyi.world"
      }
    }
  }
}

Add or change data sources

Sources are defined in the shared/sources and server/sources directories, which contain type definitions for the project. For detailed steps on adding a source, the README points to CONTRIBUTING.md.

Keep in mind that the README says the project no longer accepts contributions while the successor, NewsNext, is in development. Treat source changes as a change to your own fork.

Source definitions: shared/sources and server/sources
Contribution guide referenced: CONTRIBUTING.md

What people use it for

Scan what is currently trending in the news without a cluttered homepage
Run a personal, self-hosted news reader on your own domain
Let an MCP-compatible AI client query trending headlines through the NewsNow MCP server
Study how a TypeScript app scrapes and caches multiple sources as a reference project

Frequently asked questions

Is NewsNow free and open source?

Yes. NewsNow is released under the MIT licence, and the README credits ourongxing for the license. You can clone, modify and self-host it under those terms.

What do I need to run NewsNow locally?

You need Node.js 20 or newer and pnpm, which you enable with corepack. Docker is only required if you use the Docker deployment.

How do I install NewsNow?

Clone the repository from GitHub, run corepack enable, then pnpm i, and start with pnpm dev. The README lists these as the install commands.

Does NewsNow store full articles?

The README describes trending headlines and caching only. It does not describe full article text or a broad archive, so do not rely on it for that.

Is NewsNow still accepting contributions?

No. The README says the project no longer accepts contributions while the successor, NewsNext, is in development. A waitlist link is provided for NewsNext.

What are good alternatives to NewsNow?

The project lists Feedly, Tiny Tiny RSS, FreshRSS and Miniflux as comparable projects. Those are feed readers, so they suit people who want to manage their own RSS subscriptions rather than a trending-news view.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

NewsNow suits people who want a quick, uncluttered view of trending news, and developers who want a small self-hosted reader or an MCP connection. Skip it if you need new features or contributions, since the README says the project is no longer accepting contributions and a successor is in development, or if you need full articles or an archive.

Install options & downloads