readflow

Read your Internet article flow in one place with complete peace of mind and freedom.

Features

• Read articles from anywhere in one place.
• Save articles for offline reading or locally on you disk in the format you want (HTML, PDF, EPUB, ZIP, ...).
• Create categories and classify new articles.
• Customize article integration with a scripting engine.
• Link with external services thanks to incoming and outgoing webhooks (Newsletter, RSS, Keeper, Pocket, Shaarli, Wallabag, S3 bucket, and more...).
• Receive notifications when new articles are available.
• Enjoy the same user experience on mobile as on desktop thanks to Progressive Web App support.
• And all this without ads and trackers.

Installation

Using Go compiler:

go install -v github.com/ncarlier/readflow@latest

Or using pre-compiled binary:

curl -sf https://gobinaries.com/ncarlier/readflow | sh
# or
curl -s https://raw.githubusercontent.com/ncarlier/readflow/master/install.sh | bash

Or using Docker:

docker run -it --rm \
  -p 8080:8080 \
  -e READFLOW_DATABASE_URI=<YOUR POSTGERSQL CONNECTION STRING> \
  ncarlier/readflow:edge

Or using Docker Compose:

docker compose up

The default Docker Compose file mounts a passwd file with a demo user having demo as password.

Configuration

Readflow configuration is a TOML file that you can specify using the -c command line parameter or by setting the READFLOW_CONFIG environment variable.

You can initialize a configuration file example by using the init-config -f config.toml command.

A configuration file example can be found here.

Type readflow --help to display available commands.

UI

You can access Web UI on http://localhost:8080

CTL

readflow-ctl is a command-line client for interacting with the readflow GraphQL API from the terminal.

go install -v github.com/ncarlier/readflow/ctl@latest

It supports managing articles, categories, incoming and outgoing webhooks, and more. Authentication is handled via Basic Auth or OIDC Device Code Flow (RFC 8628).

# List articles
readflow-ctl --endpoint http://localhost:8080 articles list

# Export configuration
export READFLOW_CTL_ENDPOINT=https://api.readflow.app
export READFLOW_CTL_CLIENT_ID=YOUR_CLIENT_ID

# Get a specific article
readflow-ctl articles get 42

# List categories
readflow-ctl categories list

See the ctl/README.md for full configuration and authentication details.

MCP

readflow-ctl includes an MCP (Model Context Protocol) server that exposes readflow data to AI assistants and LLM tools.

readflow-ctl mcp

The MCP server communicates over stdio and provides read-only access through:

• Tools: list_articles, get_article, list_categories, get_category
• Resources: readflow://categories, readflow://articles/{id}, readflow://categories/{id}
• Prompts: summarize_article, suggest_categories

Example configuration for an MCP-compatible client:

{
  "mcp": {
    "readflow": {
      "type": "local",
      "command": ["readflow-ctl", "mcp"],
      "env": {
        "READFLOW_CTL_ENDPOINT": "http://localhost:8080",
        "READFLOW_CTL_USERNAME": "user",
        "READFLOW_CTL_PASSWORD": "secret"
      }
    }
  }
}

Documentation

The documentation can be found here: https://docs.readflow.app

GraphQL API

You can explore the server API using GraphiQL endpoint: http://localhost:8080/graphiql

Development

To be able to build the project you will need to:

• Install makefiles external helpers:

  $ git submodule init
  $ git submodule update
  

Then you can build the project using make:

$ make

Type make help to see other possibilities.

Bakers

These amazing people have sponsored this project:

---

Licenses

Readflow artworks except the logo are under the Licence Creative Commons Attribution-NonCommercial-NoDerivatives 4.0. Attribution to Maxime Belloche

Avatar artworks are under the License Creative Commons Attribution 4.0. Attribution to David Revoy

Readflow is provided under the GNU Affero General Public License Version 3 (AGPLv3).

Readflow is a personal news reader service.

Copyright (C) 2021 Nicolas Carlier

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>

---