Provides tools for managing RSS/Atom feeds, including subscribing, unsubscribing, fetching unread items, searching, and marking items as read.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Feedkeeper MCP Server Check my feeds and show me unread items from the last 24 hours."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. This 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).
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. 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
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 -dOpen 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 -dChanging 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.
Where | How |
Raspberry Pi | Step by step with Docker, including HTTPS and backups. |
HTTPS reverse proxy | Caddy, nginx and Traefik setup, including forwarded client IPs and MCP client setup. |
Unraid, CasaOS, Portainer | Ready-made templates for the home-lab interfaces. |
Node.js, no Docker |
|
Uberspace or any SSH host |
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. 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 topic starter packs (News, Tech, Design, etc. with crisp vector icons), single website discovery, or OPML import when setting up an empty account.
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.
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 <--> MCPEPOne 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.
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.
Create a consistent SQLite backup while FeedKeeper is running:
npm run db:backup -- /safe/location/feedkeeper.sqliteWithout 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.archiveTo restore, stop FeedKeeper first, then run:
npm run db:restore -- /safe/location/feedkeeper.sqlite --forceRestoring 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 feedkeeperRequires 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 2Open 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.)
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 startIf 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.
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).
Log in to the FeedKeeper web UI and go to Settings → Personal access tokens.
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.
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.
Tool | Description |
| List subscribed feeds with unread counts and health status, optionally only feeds with errors |
| Subscribe to a feed URL or website URL (auto-discovering the feed) |
| Discover available RSS/Atom feeds on a website URL |
| Save a web clipping, URL, or personal note to your inbox with automatic full-text and image archiving |
| Remove a subscription |
| Change a subscription's feed URL, name, poll interval, full-text setting, push notifications or app icon count; a new URL is validated before it replaces the old one |
| List folders with feed and unread counts |
| Create a folder |
| Rename a folder |
| Delete a folder; its feeds stay subscribed |
| Move a subscription into or out of a folder |
| Request an update of a subscribed feed; respects source pauses and reports pending work |
| Unread articles grouped by feed with short snippets, the cheapest way to see what is new |
| Counts for the whole account: unread and saved articles, top feeds, folders and failing feeds |
| Fetch unread items, optionally filtered by feed, search, or bookmarks; can leave out article HTML and shorten summaries |
| Page through compact items by time added; use cursors to fetch older or newly added items |
| Fetch one article and its cached content (HTML or plain text) with optional pagination ( |
| Download and cache the full article when the feed only has a teaser; use |
| Search titles and summaries across all items (with optional bookmarks filter) |
| Mark one or more items as read |
| Mark one or more items as unread |
| Mark all subscribed items as read, optionally within a feed or folder |
| Save one or more items; saved items are archived with full text and images |
| Remove bookmarks from one or more items |
| List user's active muted keywords |
| Add a keyword to automatically filter out matching articles |
| Remove a muted keyword rule |
| Export all subscribed feeds as an OPML 2.0 XML string |
| Import feeds from an OPML 2.0 XML string |
| Read the current issue, source and revision, including expired or dismissed state |
| Get compact candidates respecting app section preferences and muted keywords |
| Publish an ordered curated issue with optional structured topic overviews and a presentation layout, expiry, revision checks and safe retries |
| Compatibility request that reads the latest curated publication without changing it |
| Dismiss the shared issue with revision and replay protection |
| Read app-only section order, newspaper visibility and edition preferences |
| Patch shared app preferences without changing the web reader |
| (Admin only) Purge old items and reclaim disk space after deletions |
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.
A native app for iOS, iPadOS and macOS is in development. It uses the API under /api/v1, which is open and described in docs/openapi.yaml: pair a device with a QR code from Settings → Devices, sync your subscriptions and reading state incrementally, keep articles offline, and queue changes made without a connection. The API also provides background article preparation (/items/prepare), full-text search with FTS5, synchronized article notes, SF Symbols for sections/categories, a personal inbox (/inbox), and shared MCP-curated editions with linked overviews that stay readable between publications. App-only section order and newspaper visibility sync without changing the web reader. See the edition contract for publication, preferences and offline handling. Native push through an external relay remains planned (see docs/design/native-api.md).
Third-party clients are welcome to build on the same API — see docs/building-clients.md for a getting-started guide.
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.
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.
See .env.example for all available environment variables.
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 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.
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.
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.
Server: Node.js, TypeScript, Express, better-sqlite3, @modelcontextprotocol/sdk
Web: React, Vite, Tailwind CSS, react-i18next
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. Notable changes are listed in the changelog. This is a young project, so expect some rough edges.
This server cannot be deployed
Reddit MCP — public Reddit data via the Atom/RSS feeds.
RSS, Atom and JSON feeds for agents: find a site's feed, read items as JSON, keyless news search.
