Feedkeeper

Feedkeeper is a self-hosted RSS/Atom feed manager with a remote-capable MCP server built in. Subscribe to any feed — news sites, blogs, or a Google Alerts RSS feed — and let an MCP client like Claude read, search, and triage new items for you, from anywhere. The web UI is fully translated into English, German, and Japanese, switchable per user at any time.

It's multi-user by design: one instance can serve several people, each with their own subscriptions, read state, and API tokens.

Features

• Any RSS/Atom feed & Auto-discovery — paste a direct feed URL or simply any website URL (e.g. https://example.com/blog); Feedkeeper automatically finds and subscribes to available feeds.
• Bookmarks & Saved Articles — bookmark articles to save them for later reading, protected permanently from automatic retention cleanup.
• Muted Keywords & Word Filtering — suppress unwanted noise by configuring keyword filters that automatically hide matching articles from your feed.
• Feed Health & Error Transparency — clear visual status indicators, consecutive error counters, last successful check timestamps, and per-feed manual refresh.
• Automated Retention & Housekeeping — configurable retention rules for read items, maximum article age, and per-feed item caps, plus daily automated pruning and SQLite database vacuuming.
• Multi-user — closed by default; an admin creates accounts (or invites people through the web UI).
• Remote MCP access — connect Claude Desktop, Claude Code, or any other MCP client over HTTPS from anywhere, authenticated with a personal access token. No SSH tunnel required.
• Web UI — subscribe/unsubscribe, browse and search items, mark things read, manage tokens, users, and retention settings.
• Trilingual interface — English, German, and Japanese, with a language switcher; each user can pick their own, independent of the others.
• Per-feed control — custom label, adjustable check interval (5 minutes to 24 hours), and a "mark all read" button per feed or across everything.
• OPML import & export — seamlessly migrate subscriptions to and from other readers (Feedly, NetNewsWire, etc.) via standard OPML 2.0.
• Account self-service — change your own password from Settings.
• Self-hosting first — a single Node process, one SQLite file, no external services.
• Hardened by default — SSRF-guarded feed fetching, rate limiting, per-user data isolation, closed signup.

How it fits together

flowchart LR
    WebUI(["Web UI"])
    MCPClient(["MCP client<br/>(e.g. Claude)"])

    subgraph Server["One Node process"]
        direction LR
        API["Express API<br/>session auth"]
        MCPEP["MCP endpoint<br/>token auth"]
        DB[("SQLite +<br/>feed poller")]

        API --- DB
        MCPEP --- DB
    end

    WebUI <--> API
    MCPClient <--> MCPEP

Loading

One Node process serves the built web UI, a REST API, and an MCP endpoint (/mcp, using the Streamable HTTP transport) — all backed by the same SQLite database and feed poller.

Quick start with Docker

The fastest way to run Feedkeeper:

git clone https://github.com/visualfusion/feedkeeper.git
cd feedkeeper
docker compose up -d

Open http://localhost:3000 to complete the initial setup via the web onboarding screen.

Quick start (local development)

Requires Node.js 20+.

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 Node.js 20+.

For production, build once and run the compiled server:

npm run build
npm run start

Connecting an MCP client

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.
3. Add an MCP server entry pointing at https://<your-domain>/mcp, sending Authorization: Bearer <token> as a header.

Every tool call is scoped to the token's owner — a client can only see and manage that user's own feeds and items.

Available MCP tools

Tool	Description
list_feeds	List subscribed feeds with unread counts and health status
subscribe_feed	Subscribe to a feed URL or website URL (auto-discovering the feed)
discover_feeds	Discover available RSS/Atom/JSON feeds on any website URL
unsubscribe_feed	Remove a subscription
refresh_feed	Force an immediate check/poll of a subscribed feed
get_new_items	Fetch unread items, optionally filtered by feed, search, or bookmarks
search_items	Full-text search across all items (with optional bookmarks filter)
mark_read	Mark an item as read
bookmark_item	Save/bookmark an item for later reading
unbookmark_item	Remove bookmark from an item
list_muted_keywords	List user's active muted keywords
add_muted_keyword	Add a keyword to automatically filter out matching articles
remove_muted_keyword	Remove a muted keyword rule
export_opml	Export all subscribed feeds as an OPML 2.0 XML string
import_opml	Import feeds from an OPML 2.0 XML string
cleanup_database	(Admin only) Trigger retention housekeeping and VACUUM to purge old items and reclaim disk space

Security

• Closed signup by default (ALLOW_SIGNUP=false). An admin creates additional accounts from Settings.
• SSRF protection: feed URLs are validated (and every redirect hop re-validated) against private/internal IP ranges before being fetched, so this server can't be used to probe its own host or internal network.
• Rate limiting on login and the general API surface.
• Personal access tokens are stored as salted hashes, never in plaintext.
• 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.

Found a security issue? Please open an issue on GitHub or reach out to the maintainer directly rather than filing a public report for anything sensitive.

Configuration

See .env.example for all available environment variables.

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. This is a young project — expect some rough edges.

License

MIT

---

Built by visualfusion