rss-mcp
by jimchrist-x
README.md
# rss-mcp
An [MCP](https://modelcontextprotocol.io) 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.
## Requirements
Python 3.11+ (developed and tested on 3.12). Dependencies: `mcp>=2.3`,
`feedparser`, `httpx`.
## Install
```bash
cd rss-mcp
uv venv # or: python -m venv .venv
uv pip install -e .
```
That gives you two equivalent entry points:
```bash
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, ...):
```json
{
"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](https://github.com/open-webui/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.
```bash
# 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](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
```text
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
```sql
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
```bash
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:
```bash
.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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues