Skip to main content
Glama

rss-mcp

An MCP server that stores your RSS/Atom subscriptions in a local SQLite file and serves them to an LLM over stdio.

No accounts, no cloud, no background daemon: the client launches the server as a subprocess, the server owns feeds.db, and every tool call is a plain SQLite query plus (when you ask for it) one HTTP fetch of a feed.

MCP client ──stdio(JSON-RPC)──> rss-mcp ──> SQLite (feeds, entries)
                                    └─────> HTTP GET (feed XML, conditional)

Features

  • SQLite persistence -- one file, two tables (feeds, entries), WAL mode, (feed_id, guid) uniqueness so refreshing can never duplicate an item.

  • Conditional refresh -- ETag / If-Modified-Since validators are stored per feed, so unchanged feeds answer 304 and cost almost nothing.

  • Read API over stdio -- list, page, filter (unread/starred/since), search, and fetch an entry's full body; per-feed unread counters for triage.

  • HTML autodiscovery -- give it a blog homepage; it finds <link rel="alternate" type="application/rss+xml">.

  • OPML in/out -- migrate from any other reader and back.

  • SSRF guard -- refuses loopback/private/link-local targets (and every redirect hop is re-checked) unless RSS_MCP_ALLOW_PRIVATE_HOSTS=1.

  • Structured output -- every tool declares a Pydantic output schema, so clients get typed JSON instead of prose.

  • Bounded growth -- keeps at most RSS_MCP_MAX_ENTRIES_PER_FEED (default 500) entries per feed, never deleting starred ones.

Related MCP server: MCP RSS

Requirements

Python 3.11+ (developed and tested on 3.12). Dependencies: mcp>=2.3, feedparser, httpx.

Install

cd rss-mcp
uv venv                      # or: python -m venv .venv
uv pip install -e .

That gives you two equivalent entry points:

rss-mcp --db ./data/feeds.db        # console script
python -m rss_mcp --db ./data/feeds.db

Both speak MCP on stdio. Logs go to stderr; stdout carries JSON-RPC only.

Configure an MCP client

Add a server entry to the client config (Claude Desktop claude_desktop_config.json, MCPO config.json, Cursor, ...):

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=UTC"]
    },
    "rss": {
      "command": "uvx",
      "args": [
        "--from", "/home/you/rss-mcp",
        "rss-mcp",
        "--db", "/home/you/rss-mcp/data/feeds.db"
      ]
    }
  }
}

uvx --from <path> rss-mcp builds this checkout once, caches it and runs the console script from there, so the entry stays in the same command/args shape as any other uvx server (no venv path to maintain). Pointing command at /home/you/rss-mcp/.venv/bin/rss-mcp works too and starts faster.

With MCPO in front of Open WebUI, the same entry works unchanged inside config.json; MCPO exposes it as http://mcpo:8000/rss.

Use with MCPO / Open WebUI

MCPO proxies the stdio server as REST, one mount point per server name, so Open WebUI registers http://mcpo:8000/rss and calls POST /rss/add_feed, POST /rss/list_entries, ...

Current mcpo releases need two constraints that are easy to miss: mcp<2 (mcpo still speaks SDK v1, rss-mcp needs v2) and fastapi==0.115.12 (newer FastAPI dropped the ssl_certfile argument mcpo passes). Because of the first one, mcpo and rss-mcp cannot share a venv.

# mcpo itself, once, with the pins baked in
uv tool install "mcpo==0.0.20" --with "mcp<2" --with "fastapi==0.115.12"

# run it against the config that holds the time + rss entries
mcpo --config /home/you/config.json --host 127.0.0.1 --port 8000 --api-key change-me
# or, from this repo, with sensible local defaults (PORT=8765 etc.):
./scripts/run-mcpo-local.sh

curl -s -X POST http://127.0.0.1:8000/rss/list_feeds \
  -H "Authorization: Bearer change-me" -H 'Content-Type: application/json' -d '{}'

For the container/compose recipe (Dockerfile with two venvs, mcpo/config.docker.json, compose diff, Open WebUI registration and a troubleshooting table) see docs/MCPO.md.

Environment variables

Variable

Default

Meaning

RSS_MCP_DB

~/.local/share/rss-mcp/feeds.db ($XDG_DATA_HOME aware)

SQLite file. --db wins over this.

RSS_MCP_HTTP_TIMEOUT

20

Per-request timeout, seconds.

RSS_MCP_USER_AGENT

rss-mcp/0.1 (...)

UA string sent to feed servers.

RSS_MCP_MAX_ENTRIES_PER_FEED

500

Retention cap per feed (starred items are exempt).

RSS_MCP_MAX_DOWNLOAD_BYTES

5000000

Hard cap on a single feed download.

RSS_MCP_SUMMARY_CHARS

600

Length of the stored plain-text excerpt.

RSS_MCP_ALLOW_PRIVATE_HOSTS

0

Set 1 to allow localhost/LAN feed URLs (useful in dev).

RSS_MCP_LOG_LEVEL

INFO

stderr log level.

Tools

Tool

What it does

add_feed(url, title?, auto_discover?)

Subscribe (or refresh if already saved) and store current items.

list_feeds()

All subscriptions with entry_count / unread_count.

remove_feed(feed_id?, url?)

Delete a feed and its entries.

refresh_feed(feed_id?, url?)

Conditional GET of one feed.

refresh_all_feeds()

Refresh everything, per-feed success/failure report.

list_entries(feed_id?, limit, offset, unread_only, starred_only, since, oldest_first)

Paged reading, newest first.

get_entry(entry_id, include_content?, max_content_chars?, mark_read?)

Full item body; marks read by default.

search_entries(query, feed_id?, limit?)

Case-insensitive search over title/summary/body/author.

mark_entries(entry_ids?, feed_id?, read?, starred?)

Flag updates, including mark-all-read for one feed.

import_opml(source, limit?)

Load subscriptions from a local file or URL.

export_opml(path)

Write OPML 2.0 with every subscription.

server_info()

Version, DB path, counters.

Every tool returns a typed object (see src/rss_mcp/models.py) both as structuredContent and as a pretty-printed text block, so it works with clients that understand either.

Resources

URI

Content

rss://feeds

All subscriptions as JSON.

rss://feeds/{feed_id}/entries

Latest 20 stored entries for a feed.

rss://entries/{entry_id}

One entry with its body (read-only, does not mark it read).

Typical session

add_feed("https://blog.python.org")          -> feed id 1, 20 entries stored
list_entries(unread_only=true, limit=5)      -> 5 items, total=20, has_more=true
get_entry(17)                                -> body, marked read
search_entries("sqlite")                     -> hits across all feeds
refresh_all_feeds()                          -> 1 updated (0 new), 0 failed

Database

feeds(id, url UNIQUE, title, site_url, description, etag, last_modified,
      added_at, updated_at, last_fetched_at, last_error, is_active)

entries(id, feed_id -> feeds(id) ON DELETE CASCADE, guid, url, title, author,
        summary, content, published_at, published_ts, fetched_at,
        is_read, is_starred, UNIQUE(feed_id, guid))

Read-only views feed_overview and entry_overview add the counters and feed_title joins used by the tools. Schema version lives in PRAGMA user_version; the server refuses to open a file written by a newer schema instead of corrupting it.

Inspect it any time: sqlite3 data/feeds.db 'select id,title,url from feeds;'

Development

uv pip install -e . --group dev      # pytest + pytest-asyncio
.venv/bin/python -m pytest -q        # unit + stdio end-to-end tests
.venv/bin/rss-mcp --db ./data/feeds.db  # manual run (speaks MCP on stdin/stdout)

scripts/stdio_client.py is a tiny MCP client for poking the server without a full client app:

.venv/bin/python scripts/stdio_client.py list-tools
.venv/bin/python scripts/stdio_client.py call add_feed url=https://blog.python.org
.venv/bin/python scripts/stdio_client.py call list_entries limit=5 --text
.venv/bin/python scripts/stdio_client.py read-resource rss://feeds

Layout:

rss-mcp/
├── pyproject.toml
├── README.md
├── Dockerfile        # image with mcpo + rss-mcp in separate venvs (see docs/MCPO.md)
├── mcpo/             # ready-made MCPO configs (host + docker paths)
├── docs/MCPO.md      # step-by-step MCPO / Open WebUI integration
├── src/rss_mcp/
│   ├── config.py     # env-driven Settings
│   ├── db.py         # SQLite schema + queries
│   ├── fetcher.py    # HTTP GET (redirects, SSRF guard), feedparser
│   ├── textutil.py   # HTML -> plain text, truncation
│   ├── models.py     # Pydantic tool results
│   └── server.py     # MCPServer: tools, resources, CLI
├── tests/            # pytest, incl. stdio end-to-end
└── scripts/          # ad-hoc stdio smoke client

The tests spin up a throwaway HTTP server that serves RSS, Atom, an HTML autodiscovery page and a 304-capable endpoint, then talk to the real MCP server over a real stdio pipe -- no network access required.

Notes & limits

  • stdio is the supported transport. --transport streamable-http exists but is untested here; the tool set is identical.

  • Feed titles are never overwritten by a refresh; pass title= to add_feed again to rename one.

  • Entries are de-duplicated on their feed-provided GUID and never rewritten; a corrected item only updates after remove_feed + add_feed.

  • Feeds that emit no dates are sorted last among their feed's entries.

  • There is no scheduler: call refresh_all_feeds from your client or a cron job when you want new items.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with RSS readers that support the FreshRSS API through natural language. Allows users to manage and query their RSS feeds and articles via LLM conversations.
      7
      MIT
    • 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.
      19 npm
      5
      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