Skip to main content

rss-mcp

Agent-only MCP server for RSS and Atom. A host drives it over stdio (default) or Streamable HTTP. There is no GUI, TUI, or interactive CLI. Subscriptions, cached entries, unread state, and full-text search live in one local SQLite file. v1 is tools only: no resources, prompts, or MCP Apps.

Protocol: MCP 2026-07-28 (stdio or Streamable HTTP, tools) via the official Python SDK v2 (mcp ≥ 2.3). Design: docs/superpowers/specs/2026-11-18-rss-mcp-design.md.

Requires Python 3.11+. Install from PyPI: uv tool install rss-mcp-server gives you the rss-mcp and rss-mcp-server commands, or run it once with uvx rss-mcp-server.

Host config

In stdio mode, the process reads JSON-RPC from stdin and writes MCP messages only to stdout. It exits when stdin closes.

Cursor mcp.json (any stdio host can use the same command):

{
  "mcpServers": {
    "rss-mcp": {
      "command": "uvx",
      "args": ["rss-mcp-server"],
      "env": {
        "RSS_MCP_DB": "/absolute/path/rss.db"
      }
    }
  }
}

The PyPI distribution is rss-mcp-server (rss-mcp is blocked by a similar existing project); it installs both the rss-mcp-server and rss-mcp commands. From this checkout: uv run rss-mcp, or uvx --from /absolute/path/to/rss-mcp rss-mcp.

HTTP transport

Run the same server over Streamable HTTP instead of stdio, straight from PyPI:

uvx rss-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

After uv tool install rss-mcp-server, use rss-mcp --transport streamable-http … instead; from this checkout, uv run rss-mcp --transport streamable-http ….

Flag Default
--transport stdio (choices: stdio, streamable-http)
--host 127.0.0.1
--port 8000
--path /mcp

The MCP endpoint is then http://127.0.0.1:8000/mcp. Hosts that support remote servers can point at it directly:

{
  "mcpServers": {
    "rss-mcp": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

All sessions share one SQLite database (same RSS_MCP_DB setting). The endpoint serves both protocol eras: 2026-07-28 stateless per-request POSTs (with the MCP-Protocol-Version / Mcp-Method / Mcp-Name headers and _meta envelope) and the legacy initialize handshake (up to 2025-11-25, with sessions) for older hosts.

Set RSS_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every HTTP request (both eras; stdio is unaffected). Hosts that support custom headers:

{
  "mcpServers": {
    "rss-mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Without a token the endpoint is unauthenticated: keep the default loopback bind, or put it behind a reverse proxy with auth before exposing it beyond localhost.

Docker

The image runs the HTTP transport, stores the database in a /data volume, and runs as a non-root user:

docker build -t rss-mcp .
docker run -d --name rss-mcp --restart unless-stopped -p 127.0.0.1:8000:8000 \
  -e RSS_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  -v rss-mcp-data:/data rss-mcp

The container binds 0.0.0.0 internally (required for port mapping), so set RSS_MCP_AUTH_TOKEN whenever the published port is reachable beyond your machine. Publishing to 127.0.0.1 as above keeps it local. Run exactly one container per database volume.

Environment

Variable Default
RSS_MCP_DB ~/.local/share/rss-mcp/rss.db
RSS_MCP_USER_AGENT rss-mcp/0.1 (+https://github.com/huangcheng/rss-mcp)
RSS_MCP_AUTH_TOKEN unset (HTTP bearer auth disabled)

list_entries and search_entries use limit 20 when omitted and clamp to 0–100. Each fetch upserts at most 50 entries and sends stored ETag / Last-Modified when the feed has them.

Tools

  • add_subscription — Add a feed by URL. Repeating a URL returns the existing subscription.
  • remove_subscription — Delete a subscription and its cached entries.
  • list_subscriptions — List subscriptions with unread counts.
  • fetch_feed — Fetch one subscription, or every subscription when the id is omitted.
  • list_entries — List cached entries (article bodies omitted). Limit falls back to the server default and is clamped.
  • read_entry — Return one entry with full content. fetch_full replaces content only when article text is returned. mark_read marks it read.
  • search_entries — Full-text search over cached title, summary, and content (bodies omitted; use read_entry for full text).
  • mark_entry — Mark entries read or unread. Unknown ids are skipped.
  • import_opml — Add each OPML feed. Existing URLs are skipped.
  • export_opml — Export subscriptions as an OPML document.

Live tests

Optional network tests against a real Inoreader OPML export:

uv run pytest tests/test_real_inoreader_opml.py -v -s

They skip when /Users/huangcheng/Downloads/Cheng-Inoreader-feeds-final-20261016.opml is missing. Unit tests do not require that file.

License

MIT © 2026 HUANG Cheng

Metadata

Release files for rss-mcp-server 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rss-mcp-server 0.1.1
File Size Uploaded Provenance Actions
rss_mcp_server-0.1.1.tar.gz 109.0 kB Without provenance Details for rss_mcp_server-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rss-mcp-server 0.1.1
File Interpreter ABI Platform Actions
rss_mcp_server-0.1.1-py3-none-any.whl Python 3 none any Details for rss_mcp_server-0.1.1-py3-none-any.whl

Total release size: 126.3 kB

Release files / rss_mcp_server-0.1.1.tar.gz

Download URL rss_mcp_server-0.1.1.tar.gz
Size 109.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f25b1ac041ca2c052c3039bc4e4cf7755a70681d269f668e29d558ff17035d80
BLAKE2b-256 checksum
How to use checksums
974f4d0dfefa869e654036d26c8edf600ea3f9ac1a5596b0ed76338a38880fa8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / rss_mcp_server-0.1.1-py3-none-any.whl

Download URL rss_mcp_server-0.1.1-py3-none-any.whl
Size 17.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1a7b945bb01c7f8121232fedf52a08ad99491a0f2e3e2f7bcdfb2e5b67830a77
BLAKE2b-256 checksum
How to use checksums
ee6a73bb995b0ade0218bd2debe6bfad52082918f06721391e4f89b1f9b2fab5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for rss-mcp-server 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page