FeedKeeper MCP server

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.

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

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.
Coolify, Unraid, CasaOS, Portainer	Ready-made templates for self-hosting and home-lab platforms.
Node.js, no Docker	npx feedkeeper runs it with no clone and no build, see Running FeedKeeper with Node.js.
Uberspace or any SSH host	Deploying to Uberspace.

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."