Skip to main content
Glama

rss-mcp - Superduper local-first RSS reader + readability extractor

CI FastMCP Python 3.13 License: MIT

Subscribe to feeds, get clean article text without ad sites, full-text + semantic search. Pure local SQLite, no account needed.

Features & Preview

  • Dashboard: High-level KPIs (feeds, total items, unread, starred).

  • 3-Pane Reader: Feeds navigation, articles stream, and clean readability text extract pane.

  • Feeds Manager: OPML import/export, feed health audits, refresh triggers.

  • Inbox & Starred: Unified triage inbox and starred bookmarks.

  • RAG & Search: FTS5 SQLite full-text search combined with LanceDB semantic vector sweeps.

  • Chat & LLM: Built-in LLM exploration assistant with dynamic provider detection (Ollama, LM Studio, etc.).

Related MCP server: feedkit

Framework Stack

  • Backend: FastMCP 3.1+, Starlette / Uvicorn, SQLite3 WAL + FTS5, Trafilatura, LanceDB, Pyright (zero errors).

  • Frontend: React 19, TypeScript, Vite, Tailwind CSS, Zustand, Lucide React, Biome linter.

Install & Run

Option

Command

A naked PC

pwsh -File start.ps1 (installs uv/bun via winget as needed)

B dev backend

uv sync ; uv run python -m rss_mcp --serve

C stdio (Claude Desktop)

uv run python -m rss_mcp

D frontend

cd webapp ; bun install ; bun run dev --port 11975

See INSTALL.md. Onboarding: N/A (pure local util, no wrappee/account) - rationale in docs/DEVELOPMENT.md.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rss-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "d:/Dev/repos/rss-mcp",
        "run",
        "python",
        "-m",
        "rss_mcp"
      ]
    }
  }
}

Environment Variables

Variable

Default

Description

RSS_MCP_PORT

11974

Backend server port (strict fleet standard)

RSS_MCP_WEBAPP_PORT

11975

Webapp frontend port

RSS_MCP_HOST

127.0.0.1

Host address to bind to

RSS_MCP_DB

data/rss.sqlite3

SQLite database file path

RSS_MCP_LANCE_PATH

data/lancedb

LanceDB vector database directory

Tools (all real, no stubs)

  • feeds_ops: subscribe, unsubscribe, list_feeds, refresh_feed, refresh_all, fetch_items, get_item, mark_read, mark_star, remove_item, opml_import, opml_export, feed_health

  • readability_ops: extract, get_cached, clear_cache, list_extractors

  • reader_ops: inbox, starred, search_text, search_semantic, stats, trigger_sweep, sweep_status

  • show_reader_prefab_card: Prefab card view for visual readers

  • rss_help: Interactive help and quickstart

  • rss_shutdown: Clean server termination

Ports

Backend 11974, frontend 11975. Forbidden ports are never used (3000, 5000, 5173, 8000, 8080).

Install (.mcpb for Claude Desktop)

  • Claude Desktop: install rss-mcp.mcpb from the latest GitHub release (releases/latest/download/rss-mcp.mcpb), then run install.ps1.

  • Other clients (Cursor/Codex/CLI): uvx rss-mcp (stdio transport, same tools as the bundle).

vs glance-mcp

glance-mcp is a lightweight holdall (single-shot fetch, weather, probes). rss-mcp is the stateful full reader: subscriptions, polling with ETag, readability cache, FTS5, stars, OPML, background sweeps.

Development

  • Justfile shortcuts: just lint, just typecheck, just test, just ci, just gates-green

  • Biome check: bun run biome:ci (in webapp/)

  • Pre-commit hook: powershell.exe -NoProfile -File scripts/pre-commit-biome.ps1

  • Pack MCPB bundle: powershell.exe -NoProfile -File scripts/mcpb-pack.ps1

Available Tools

6 tools
feeds_opsB

feeds_ops - Full feed subscription lifecycle.

RATIONALE: groups subscribe/unsubscribe/list/refresh/fetch/get/mark/star/remove/opml/health into one discoverable tool. Stateful reader, unlike glance-mcp single-shot fetch.

Return Format

Dictionary with success (bool), message (str), and operation-specific payload (e.g. feeds, items, feed, opml).

Examples

  • {"operation": "list_feeds"} -> lists all subscribed feeds.

  • {"operation": "subscribe", "url": "https://news.ycombinator.com/rss"} -> subscribes to RSS feed.

  • {"operation": "refresh_all"} -> polls all feeds for new articles.

  • {"operation": "fetch_items", "limit": 20, "unread_only": true} -> retrieves unread articles.

Inputs: operation (required), url, limit, title, +6 more. Returns: object

readability_opsA

readability_ops - Clean article text without ad sites.

RATIONALE: trafilatura primary plus readability-lxml fallback, cached in SQLite. No paywall bypass: if the page needs login, extraction reports failure honestly.

Return Format

Dictionary with success (bool), message (str), and article text fields (title, author, text, html, extractor, cached).

Examples

  • {"operation": "extract", "item_id": 3} -> downloads article and extracts cleaned text.

  • {"operation": "get_cached", "item_id": 3} -> retrieves previously cached clean extraction.

  • {"operation": "list_extractors"} -> lists available readability engines.

Inputs: operation (required), force, item_id. Returns: object

reader_opsA

reader_ops - Daily reading surface: inbox, stars, search, stats, RAG sweeps.

RATIONALE: single entry point for what a human checks every morning.

Return Format

{success, message, items/stats/job/job_id/status/chunks}

Examples

  • {"operation": "inbox"} unread items

  • {"operation": "search_text", "query": "vienna"} FTS search

  • {"operation": "search_semantic", "query": "rocket engine"} vector search

  • {"operation": "trigger_sweep", "mode": "incremental", "hours": 4} background index job

Inputs: operation (required), ctx, mode, hours, +4 more. Returns: object

rss_helpB

rss_help - Capability summary and op list.

Return Format

Dictionary with success (bool), message (str), registered tools, ports, and comparison vs glance-mcp.

Examples

  • {} -> summary of reader capabilities and registered tools.

Inputs: no named parameters. Returns: object

rss_shutdownA

rss_shutdown - Graceful shutdown hook for the daemon.

Return Format

Dictionary with success (bool) and acknowledgement message (str).

Examples

  • {} -> acknowledges shutdown request.

Inputs: no named parameters. Returns: object

show_reader_prefab_cardB

show_reader_prefab_card - Prefab stats card for list/status/stats coverage.

Return Format

ToolResult with PrefabApp structured content plus plain-text fallback.

Examples

  • {} -> renders reader stats card.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation3/5

    feeds_ops and reader_ops both handle item retrieval and marking (e.g., fetch_items vs. inbox, mark/star in feeds_ops vs. stars in reader_ops), creating overlap that could cause misselection. show_reader_prefab_card also overlaps with reader_ops stats. Descriptions clarify intended separation, but boundaries are not crisp.

    Naming Consistency3/5

    Most tools use a consistent noun_ops pattern (feeds_ops, readability_ops, reader_ops), but rss_help and rss_shutdown use a different prefix, and show_reader_prefab_card uses a verb_noun format. The mix is readable but not predictable.

    Tool Count5/5

    Six tools is well-scoped for an RSS reader daemon. Each tool has a clear role: feed lifecycle, extraction, reading surface, help, shutdown, and a presentation card. None feels redundant or excessive.

    Completeness5/5

    The surface covers the full RSS reader lifecycle: subscription management (subscribe/unsubscribe/list/refresh/remove/OPML/health), article extraction and caching, reading inbox/stars/search/stats, background RAG sweeps, help, and graceful shutdown. No obvious operational gaps remain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables intelligent RSS feed management with AI-powered semantic search, advanced filtering, and a comprehensive reading workflow. Supports OPML parsing, article organization with status tracking, and token-efficient browsing of large feed collections.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to search a curated RSS/Atom catalog, subscribe to and collect feeds, and query collected articles through natural-language tools.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables querying a local SQLite database of curated RSS/Atom/RDF feeds through tools for latest headlines with filters, keyword search, cross-outlet coverage comparison, and source/freshness listing. Items are kept in their original language so an LLM can translate, summarize, and compare framing at query time.
      4
      Mozilla Public 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching, reading, and privately archiving news from supported publisher subscriptions, with per-user authentication via human sign-in links and separate tokens, sessions, and archives.
      321 PyPI
      1
      MIT