FeedKeeper

FeedKeeper is an independent RSS and Atom feed manager built for people who want full ownership over their subscriptions. It runs quietly on your own server or Raspberry Pi, stores everything in a local SQLite database, and requires zero cloud accounts.

Beyond a clean web reader, FeedKeeper includes a native, authenticated Model Context Protocol (MCP) endpoint. Listed in the official MCP Registry (io.github.visualfusion/feedkeeper) and verified for the Anthropic Claude Directory, it lets MCP clients read, search, bookmark, and organize your feeds over a remote connection. Your subscriptions and reading history stay in your own SQLite database.

It is multi-user by default, with isolated accounts, personal access tokens, and a trilingual interface (English, German, and Japanese).

Why FeedKeeper?

There are good self-hosted readers already, such as Miniflux and FreshRSS. FeedKeeper is for you if you want your feeds to be part of your AI workflows without giving up ownership:

• MCP built in. Claude, ChatGPT and other MCP clients connect to /mcp directly, with OAuth sign-in or personal access tokens, read-only or read and write. FeedKeeper is listed in the official Model Context Protocol Registry (io.github.visualfusion/feedkeeper) and verified in Claude's connector directory. Ask for a daily briefing, let an agent triage unread articles, or let it curate an edition. No separate bridge to run.

• Small to run. One Node process and one SQLite file, with full-text search built in. No PostgreSQL, no Redis. It runs on a Raspberry Pi or on shared hosting such as Uberspace.

• An open API. The REST API under /api/v1 is described in an OpenAPI file, with offline sync, notes and editions, so third parties can build their own clients.

• Built to be extended. Operators can add settings, footer links or a single sign-on form to the web app without forking it, see Extending the web app.

If you only need a plain, mature reader with many integrations, the established projects are the safer choice. FeedKeeper is young (version 0.x), so expect some rough edges.

Related MCP server: RSS Feed MCP Server

Quick start

Up and running in about a minute. Prebuilt images for amd64 and arm64 (including Raspberry Pi) are published to the GitHub Container Registry. You only need Docker, no clone and no build:

mkdir feedkeeper && cd feedkeeper
curl -fsSLO https://raw.githubusercontent.com/visualfusion/feedkeeper/main/compose.yaml
echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env
docker compose up -d

Open http://localhost:3000 to complete the initial setup via the web onboarding screen. For a public domain, also add PUBLIC_URL=https://your.domain to .env (see .env.example for all options).

Just want to look around? npx feedkeeper starts it without Docker (it needs a supported Node.js, see Running FeedKeeper with Node.js); the data stays in ~/.feedkeeper.

To update, pull the new image and restart:

docker compose pull
docker compose up -d

Changing SESSION_SECRET signs out active browser sessions and makes stored two-factor keys unreadable (see Account security); feeds and accounts stay in the database. Want to build the image yourself? Clone the repository and run docker compose -f compose.yaml -f compose.build.yaml up -d --build.

Started without a SESSION_SECRET (for example from one of the templates below), the image creates one on the first start and keeps it in the data volume.

Set up with an AI agent (Claude Code, Cursor, Codex)

If you use an AI coding assistant on your server or local machine, you can paste this prompt:

"Set up and start FeedKeeper on this machine using Docker Compose. Download or reference the template from https://raw.githubusercontent.com/visualfusion/feedkeeper/main/compose.yaml, generate a secure 64-character SESSION_SECRET, set PUBLIC_URL to the address this machine is reachable at, ensure the feedkeeper_data volume is persistent, start the container, and verify that the web onboarding responds on port 3000."

Other ways to run it

Features

• Categories and feed ordering — group subscriptions into categories, search and filter the feed list, rename categories in place, and reorder feeds by dragging.

• Smart feed discovery — paste a direct feed link or a website address (like example.com/blog); FeedKeeper finds RSS and Atom feeds, including ones listed on a site's feed overview page, and checks each one before subscribing.

• Reliable feed updates — fetch several feeds at once with limits per source. Slow feeds and temporary failures do not hold up other updates, and unfinished work resumes after a restart.

• Automatic character encoding — parses standard UTF-8 as well as legacy ISO-8859-1/Windows-1252 feeds without garbled umlauts or broken symbols.

• Saved articles as a lasting archive — star an article to save it: FeedKeeper keeps its full text and stores its images next to the database, so it stays readable even if the source changes. Saved articles survive cleanups and unsubscribing, ignore the word filter, and their full text is searchable.

• Full-text search — indexed with SQLite FTS5 across titles, snippets, cached full text, and personal notes. Ranked by BM25 relevance with diacritic-insensitive matching and phrase support.

• Article notes and lasting knowledge — attach personal Markdown notes to any article. Notes sync across devices, export to standalone Markdown files, and protect articles permanently from retention cleanups.

• Authoritative feed icons — icons are cached on the server with SHA-256 hashes and conditional ETags, so devices load them fast without third-party requests.

• Keyword mute filters — cut through information overload by filtering out articles matching specific keywords before they reach your stream.

• Empty gallery filtering — gallery links with no editorial text (only an image or a read-more prompt) stay out of article lists, search, notifications and curation. Short news and captions remain visible; saved or annotated items remain accessible. Nothing is deleted.

• Health monitoring — clear status indicators show polling health, consecutive fetch errors, and timestamps so you instantly spot dead feeds.

• Universal Inbox (Read-it-Later) — save web clippings, URLs, and personal notes directly to your personal inbox from any browser, share extension, or MCP client. Full article contents and lead images are automatically extracted and archived offline.

• Curated editions & daily briefings — finite morning, midday, and evening editions. Curated by external agents via MCP (e.g. Claude, local LLMs, or custom scripts), with structured, linked editorial overviews. The latest publication remains available until its successor is published. Candidates and publication require readable body text beyond a repeated headline or read-more/player prompt, regardless of publisher or URL. Video/audio-only entries stay in the library but out of new editions; short reports, summaries and transcripts remain eligible. Existing editions are unchanged.

• Automated database housekeeping — sensible defaults prune read articles, enforce maximum item retention, and run SQLite VACUUM on schedule to keep storage lean.

• Remote MCP access — stream items directly into Claude or any MCP-compatible environment via standard Streamable HTTP, with read-only or read-write tokens, OAuth sign-in for connectors such as ChatGPT and Claude (consent page, PKCE, revocable in Settings), and cursor-based paging for incremental sync.

• Privacy & self-hosting first — a single Node.js process and one SQLite file. No external database engines, no telemetry, no tracking.

• OPML 2.0 import & export — switch back and forth from Feedly, NetNewsWire, Inoreader, or Reeder at any time.

• Article reader & background preparation — read feed content in the app, with shared, bounded full-text extraction, durable retries and source-host limits. Full-text fetching can be tuned per subscription. Reader content omits repeated author and date lines, including standalone inline bylines, while keeping attribution when no author is provided separately. Videos, social posts and audio players, including those held back by consent plugins, become one link that clients show as a card, and lists of related or popular articles inside an article are removed. The cleanup is a set of small content rules that the community can extend. See full-text fetching for settings and operating limits.

• List and newspaper views — switch between a compact list and an editorial layout with wide lead stories and longer previews; phones always use the newspaper layout.

• Mobile-friendly web app — responsive layout with tab navigation and pull to refresh, installable on the home screen, with light, dark and system themes.

• Works offline — a service worker lets the installed app start without a connection. It keeps your saved articles and the newest unread ones on the device with their full text and images, so you can read, search and filter them on the train. Changes such as marking read or saving are kept and sent once you are back online. Switch it off in the settings; cached data is removed when you log out.

• Notifications and home screen shortcuts — optional push notifications for new articles of the feeds you choose (on iPhone and iPad once the app is on the home screen), the number of unread articles of the feeds you choose on the app icon, shortcuts to saved articles and to adding a feed, and sharing a web address from another app straight into the add-feed dialog. Notifications are encrypted end to end and delivered through your browser vendor's push service; the server creates its push keys on first start and keeps them in the database.

• Personal profiles — each account can set its display name and a profile photo.

• Online backups — create verified SQLite backups while the service keeps running.

• Guided onboarding & starter packs — get started instantly with curated feed lists by interest (News, Technology, Apple, Development, Science, Design, Gaming, Business, Sport, Culture), each feed with a short description and feeds from several lists in one go, single website discovery, or OPML import when setting up an empty account. The lists are served to the native apps too (GET /api/v1/feed-lists).

• Passkeys with browser autofill & step-up reauthentication — sign in effortlessly without a password via WebAuthn browser autofill directly from the email input field. Protect security-sensitive actions (passkey registration, 2FA setup, recovery codes) with modal biometric confirmation without typing a password. Optional TOTP two-factor authentication and one-time recovery codes on every installation; see Account security.

• Hardened security — SSRF protection against internal network probing, rate limiting on authentication, and hashed API tokens.

How it fits together

flowchart LR
    WebUI(["Web reader"])
    NativeApp(["Native app / clients<br/>(iOS, iPadOS, macOS)"])
    MCPClient(["MCP client<br/>(e.g. Claude)"])

    subgraph Server["One Node process"]
        direction TB
        WebAPI["Web session API"]
        NativeAPI["Native REST API (/api/v1)<br/>device & bearer tokens"]
        MCPEP["MCP endpoint (/mcp)<br/>streamable HTTP"]
        DB[("SQLite + FTS5<br/>feed poller & sync engine")]

        WebAPI --- DB
        NativeAPI --- DB
        MCPEP --- DB
    end

    WebUI <--> WebAPI
    NativeApp <--> NativeAPI
    MCPClient <--> MCPEP

One Node process serves the built web reader, the open REST API (/api/v1), and an MCP endpoint (/mcp, using the Streamable HTTP transport) — all backed by a single SQLite database, the FTS5 search index, and the feed poller.

Web reader, native apps, and MCP

FeedKeeper uses a single backend with clients tailored to different situations:

• The web reader is a straightforward browser interface for day-to-day reading, categorizing feeds, and triaging your stream.

• Native apps (iOS, iPadOS, macOS) build on platform features: offline sync via SQLite change logs, personal Markdown notes per article, and daily newspaper editions.

• Remote MCP access lets AI tools curate reading lists, search past items, and inspect candidates using the same APIs.

Features developed for native apps (such as article notes and edition scheduling) are exposed through the open API (/api/v1) so third-party clients can use them too.

Back up and restore

Create a consistent SQLite backup while FeedKeeper is running:

npm run db:backup -- /safe/location/feedkeeper.sqlite

Without Docker, run npm run build once before using the backup commands. The command refuses to overwrite an existing backup and verifies its integrity. Images of saved articles live in an archive folder next to the database (configurable with ARCHIVE_PATH); the backup copies them to <backup>.archive and restore puts them back. A backup holds the database and the archive, not SESSION_SECRET: keep the secret with your backups, because it also protects the two-factor keys in the database (see Account security). Keep the backup outside the application directory and copy it to another machine or storage device.

With Docker Compose, create the backup in the mounted data volume and copy it to the host:

docker compose exec feedkeeper node server/dist/feedkeeper.js backup /app/data/feedkeeper-backup.sqlite
docker compose cp feedkeeper:/app/data/feedkeeper-backup.sqlite ./feedkeeper-backup.sqlite
# only present if you have saved articles with images:
docker compose cp feedkeeper:/app/data/feedkeeper-backup.sqlite.archive ./feedkeeper-backup.sqlite.archive

To restore, stop FeedKeeper first, then run:

npm run db:restore -- /safe/location/feedkeeper.sqlite --force

Restoring replaces the configured database. Start FeedKeeper again after the command succeeds. Existing backups may need a database migration on startup if they were created with an older version.

For Docker Compose, stop the service and run the restore command in a one-off container with the backup mounted read-only:

docker compose stop feedkeeper
docker compose run --rm --no-deps -v "$PWD/feedkeeper-backup.sqlite:/restore.sqlite:ro" feedkeeper node server/dist/feedkeeper.js restore /restore.sqlite --force
docker compose up -d feedkeeper

Quick start (local development)

Requires Node.js 22.22.2+ (22.x), 24.15+ (24.x), or 26+.

git clone https://github.com/visualfusion/feedkeeper.git
cd feedkeeper
npm install
cp .env.example .env
# edit .env — at minimum, set SESSION_SECRET (see the comment in the file)
npm run dev:server   # terminal 1
npm run dev:web      # terminal 2

Open http://localhost:5173 and follow the onboarding screen to create the first admin account. (Prefer the terminal? npm run setup does the same thing without a browser.)

Deploying

See docs/deployment-uberspace.md for a step-by-step guide to running FeedKeeper on Uberspace. The same steps work on any Linux host with SSH access and a supported Node.js version.

For production, build once and run the compiled server:

npm run build
npm run start

Hosted option

If you would rather not operate a server, FeedKeeper Cloud is a hosted edition run by the same maintainers. This repository stays MIT-licensed and fully self-hostable.

Connecting an MCP client

Local stdio mode (Claude Desktop & local tooling). Run feedkeeper mcp (or node server/dist/mcp-stdio.js) to start a local stdio MCP server backed by your SQLite database without needing an open port or network configuration.

With OAuth (ChatGPT, Claude and other connectors). Add https://<your-domain>/mcp as a remote MCP server or custom connector. The client discovers the sign-in on its own: you log in to FeedKeeper, choose read only or read and write on the consent page, and the client gets a short-lived token (1 hour, refreshed for 30 days). Connected AI assistants are listed under Settings → MCP and can be disconnected at any time. OAUTH_ALLOWED_REDIRECT_HOSTS can limit which hosts may register. Set PUBLIC_URL to the address the client reaches the server at; see docs/design/mcp-oauth.md.

With a personal access token (scripts and clients without OAuth).

1. Log in to the FeedKeeper web UI and go to Settings → Personal access tokens.

2. Create a token and copy it immediately — it's only shown once. Choose Read only for clients that only need to browse articles; choose Read and write to let the client change feeds or reading state. Existing tokens retain their previous write access.

3. Add an MCP server entry pointing at https://<your-domain>/mcp, sending Authorization: Bearer <token> as a header. Settings → MCP also offers a ready-made Claude Desktop configuration.

Every tool call is scoped to the signed-in user — a client can only see and manage that user's own feeds and items. OAuth tokens work only on /mcp.

Connect via AI assistant prompt

To have an AI assistant configure the MCP connection for you, create a Personal Access Token in Settings → Personal access tokens and run:

"Add FeedKeeper as a remote HTTP MCP server pointing to https:///mcp with Authorization: Bearer to my MCP configuration (e.g. claude_desktop_config.json or Cursor MCP settings). Verify the connection by listing my feeds."

Available MCP tools

Besides tools, the server offers prompts (daily_briefing, catch_up_on_topic, saved_reading_list, triage_unread) and resources (feedkeeper://feeds, opml, saved, digest and feedkeeper://items/{id}) that clients can show as ready-made actions.

Read-only tokens expose only the tools that leave FeedKeeper data unchanged. get_item returns stored feed or reader content; fetch_full_text downloads the article from its website and needs a read-and-write token. Item actions accept a single itemId or up to 200 itemIds. get_new_items, search_items and list_items accept since and until (ISO date or date-time) to filter by publish date. For incremental synchronization, save newestCursor, pass it as after next time, and follow nextCursor as before until there are no more pages.

Native apps

For reading on the go and offline, the official FeedKeeper app is available on the App Store for iOS, iPadOS, and macOS. It pairs directly with your self-hosted instance in seconds — just scan the pairing QR code under Settings → Devices in your web reader.

The app builds on FeedKeeper's open native API (/api/v1) to provide:

• Incremental delta-sync and offline article caching

• Offline action queuing (reading state, stars, and folders sync back automatically)

• Fast full-text search powered by SQLite FTS5

• Synchronized personal Markdown notes per article

• Reading layout preferences and daily newspaper editions

The built-in web reader remains 100% free and fully supported. The native sync API is open and documented in docs/openapi.yaml — third-party and community clients are warmly encouraged to build on the same endpoints (see docs/building-clients.md for a getting-started guide).

Security

• Closed signup by default (ALLOW_SIGNUP=false). An admin creates additional accounts from Settings.

• SSRF protection: feed URLs and redirects are checked before fetching and again when connecting. Private/internal addresses are blocked by default. On trusted instances that need local feeds, set ALLOW_PRIVATE_FEEDS=true.

• Blocked sources: list domains in BLOCKED_FEED_HOSTS (comma-separated, subdomains included) to keep them out of your instance. Subscribing, polling, article text and images are refused for them with the error feed_blocked. Feeds already stored stop updating and lose their articles, except saved ones, ones with notes and ones in a published edition. Restart the server after changing the list.

• Rate limiting on login and the general API surface.

• Personal access tokens are stored as salted hashes, never in plaintext.

• OAuth 2.1 for MCP with required PKCE, expiring tokens, refresh-token rotation with reuse detection, and a consent page that asks every time.

• Behind a proxy or CDN: TRUST_PROXY and CLIENT_IP_HEADER make sure rate limits see the real client address.

• Per-user data isolation: every query is scoped to the authenticated user; feeds are deduplicated by URL under the hood, but subscriptions, read state, and tokens are always per-user.

Feed icons and the images of saved articles are delivered by the FeedKeeper server, so browsing does not contact third-party sites for them; images of other articles still load from their source websites. To find a feed's icon, the server fetches the site's homepage about once a week. Opening a full article through the reader also fetches that page from the FeedKeeper server.

Found a security issue? Please report it privately as described in SECURITY.md instead of opening a public issue.

Configuration

See .env.example for all available environment variables.

Feed updates

By default, FeedKeeper checks up to four feeds at once, with at most two requests per source hostname. Scheduled and manual updates, new subscriptions, OPML imports and MCP share the same queue. A manual refresh may stay pending when a source is busy or has asked for a pause; the web reader tells you when this happens.

Run one application process per database. On hosts with little memory, start with POLL_CONCURRENCY=2 and POLL_HOST_CONCURRENCY=1. Allow 45 seconds for shutdown; the supplied Docker Compose file already does this. See Feed polling for the settings, logs and upgrade guidance.

Reader cleanup

Reader HTML is cleaned when served, without rewriting stored publisher content. Exact adjacent image copies (for example separate desktop/mobile elements) collapse to one; different sources, links, responsive sources, captions and repetitions separated by text remain distinct. Empty product-card headers and ad slots are removed using their container structure and German, English and Japanese labels. Existing advertising content, affiliate disclosures and sponsored-article labels remain readable. These rules also apply to previously stored articles when requested again; downloaded client copies need to refresh before they reflect a server update.

Article images

The image proxy shares downloads and cached images between subscribers of the same feed. This covers native clients requesting proxy images and the web app's offline copies; images loaded directly from a publisher bypass this cache. Every request still checks access to the article and its image. Different feeds and different source URLs, including query parameters, have separate cache entries.

The disposable cache defaults to 256 MiB, 2,000 images and six hours, with four active jobs and at most 32 waiting jobs. Full queues return 503 image_busy with Retry-After: 1. Downloads retain the existing HTTP limits, size limit, SSRF checks and redirect rules; POLL_REQUEST_TIMEOUT_MS also bounds time spent waiting in the image queue. Missing images (HTTP 404/410) and unsupported formats are remembered for 60 seconds; other failures are not cached. Source cache directives can shorten or prevent disk caching.

The web reader binds offline article snapshots and queued changes to the authenticated account. Account switches invalidate private service-worker responses, including when the previous session expired without an explicit logout; in-flight responses cannot refill a later session's cache. Legacy snapshots without account ownership are discarded and downloaded again. A change in another tab revokes that tab's offline account binding until authentication is refreshed.

Normal proxied article images use private cache lifetimes of at most six hours and a content ETag. Browsers and the web offline cache revalidate them; archived images keep their fixed version. A new proxy URL version lets existing clients move away from the previous year-long immutable policy.

See IMAGE_CACHE_* in .env.example to change these limits. IMAGE_CACHE_PATH defaults to image-cache next to the database. Use one process per cache directory and keep it separate from ARCHIVE_PATH. Expired and least recently used entries are removed automatically. The cache stores hashed keys rather than source URLs, uses asynchronous file operations, and does not write to SQLite on cache hits. Once used, it logs aggregate image_cache counters every minute: hits, misses, shared work, negative hits, errors, overloads, evictions, bytes, entries, active and waiting jobs.

Saved articles retain their permanent archives. Cache and archive files share disk space through hard links when they are on the same filesystem; otherwise saving an article copies its image. Evicting the cache never deletes a saved copy. Existing archives can refill the cache without contacting the source; these snapshots stay tied to their article so an old saved image cannot replace a newer one at the same source URL. Back up the database and archive as before; the disposable cache needs no backup.

No database migration is needed. To roll back, stop the application and return to the previous version. Alternatively, set IMAGE_CACHE_MAX_BYTES=0 and restart to disable disk caching; IMAGE_CACHE_NEGATIVE_TTL_SECONDS=0 also disables remembered failures. Existing disposable files can be removed while the application is stopped. Keep the archive.

Extending

Operators and products built on FeedKeeper can add settings sections, footer links, a page title and a custom sign-in to the web app through window.feedkeeperExtensions, without patching the code. FeedKeeper Cloud, the hosted edition, uses it for its membership settings. See Extending the web app.

Tech stack

• Server: Node.js, TypeScript, Express, better-sqlite3, @modelcontextprotocol/sdk

• Web: React, Vite, Tailwind CSS, react-i18next

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for how to get started. Improving or adding a language is a good first contribution, see docs/translating.md. So is a better starter feed for the lists new users see, see docs/feed-lists.md. Notable changes are listed in the changelog. This is a young project, so expect some rough edges.

License

MIT