{
"markdown": "# freshrss-mcp\n\n\n\n[](https://github.com/ni-c/freshrss-mcp/actions/workflows/ci.yml)\n[](https://scorecard.dev/viewer/?uri=github.com/ni-c/freshrss-mcp)\n![\"Socket](\"https://socket.dev/api/badge/npm/package/@ni-c/freshrss-mcp\")
\n[](https://glama.ai/mcp/servers/ni-c/freshrss-mcp)\n
\n[](https://www.npmjs.com/package/@ni-c/freshrss-mcp)\n[](https://github.com/ni-c/freshrss-mcp/pkgs/container/freshrss-mcp)\n[](https://mcp-hub.ni-c.de)\n
\n[](https://freshrss-mcp.ni-c.de)\n[](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for\n[FreshRSS](https://freshrss.org), the self-hosted RSS and Atom feed aggregator.\n\nLets MCP clients like Claude Code, Claude Desktop or Codex work through your feeds:\nsee what is unread, read the articles, mark them, and manage subscriptions and\ncategories.\n\nSixteen tools is the ceiling, not the floor: `FRESHRSS_ALLOW_TOOLS=essential`\nregisters a curated seven instead, and a model picks the right tool far more\nreliably from seven than from sixteen — see\n[choosing which tools load](#choosing-which-tools-load).\n\nIt speaks the Google Reader compatible API that FreshRSS exposes at\n`/api/greader.php`, and hides that API's quirks behind tool arguments an assistant can\nactually use: numeric feed ids, category and label names, ISO dates and decimal\narticle ids instead of `user/-/state/com.google/…` stream identifiers and hexadecimal\nitem tags.\n\n\n\n \n \n ![\"An](\"https://freshrss-mcp.ni-c.de/architecture.svg\")
\n\n\n\n\n\n\n## What makes it different\n\n**Sixteen tools, no stream ids.** The Google Reader API speaks in stream\nidentifiers and hexadecimal item tags. These tools take numeric feed ids,\ncategory and label names, ISO dates and decimal article ids, and hand back plain\ntext instead of raw HTML.\n\n**Built for untrusted feeds.** Every article was written by a stranger on the\ninternet, so responses are marked as data, feed URLs are stripped of credentials,\nand article text is capped per article and per response. The five irreversible\ntools ask a person first, through MCP elicitation.\n\n## Requirements\n\n- Node.js 22 or newer\n- A FreshRSS instance (developed against 1.29) with\n - the API enabled: **Settings → Authentication → \"Allow API access\"**\n - an **API password** set for the user: **Settings → Profile → API management**.\n This is a separate password from the web login.\n\n## Configuration\n\n| Variable | Required | Description |\n| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |\n| `FRESHRSS_URL` | yes | Root URL of the instance, e.g. `https://rss.example.com`. The API path `/api/greader.php` is appended automatically. |\n| `FRESHRSS_USER` | yes | FreshRSS user name. |\n| `FRESHRSS_API_PASSWORD` | yes | The **API password** from the profile page, not the web login password. |\n| `FRESHRSS_READ_ONLY` | no | `1`, `true` or `yes` registers only the read tools. |\n| `FRESHRSS_INSECURE_TLS` | no | `true` accepts self-signed certificates for this connection only. |\n| `FRESHRSS_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |\n| `FRESHRSS_DENY_TOOLS` | no | Same syntax; removed from whatever `FRESHRSS_ALLOW_TOOLS` left |\n| `ELICITATION` | no | `false` replaces the approval dialog with the two-call token. **Not prefixed.** |\n\nThe server starts without credentials so its tools stay listable; every call\nthen fails with these setup instructions.\n\n### Choosing which tools load\n\n`FRESHRSS_ALLOW_TOOLS` and `FRESHRSS_DENY_TOOLS` take comma-separated tool names;\na trailing `*` matches a whole family. `essential` is a curated preset of\nseven: `list_feeds`, `list_categories`, `get_unread_counts`, `list_articles`, `get_articles`, `mark_articles`, `mark_all_as_read`.\n\n```sh\nFRESHRSS_ALLOW_TOOLS=essential\nFRESHRSS_ALLOW_TOOLS=list_feeds,list_articles,mark_articles\nFRESHRSS_DENY_TOOLS=delete_*\n```\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot\nsilently hide a tool — an absent tool is not something anyone traces back to an\nenvironment variable. A filtered tool is never registered, so it is absent from\n`tools/list` and unknown to `tools/call` alike, exactly like a write tool under\n`FRESHRSS_READ_ONLY`.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)\nis the other answer — its `/hub` endpoint replaces every server's tools with six\nmeta-tools.\n\n## Installation\n\n### Claude Code\n\n```sh\nclaude mcp add freshrss -- npx -y @ni-c/freshrss-mcp\n```\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"freshrss\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/freshrss-mcp\"],\n \"env\": {\n \"FRESHRSS_URL\": \"https://rss.example.com\",\n \"FRESHRSS_USER\": \"alice\",\n \"FRESHRSS_API_PASSWORD\": \"…\"\n }\n }\n }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.freshrss]\ncommand = \"npx\"\nargs = [\"-y\", \"@ni-c/freshrss-mcp\"]\nenv = { FRESHRSS_URL = \"https://rss.example.com\", FRESHRSS_USER = \"alice\", FRESHRSS_API_PASSWORD = \"…\" }\n```\n\n### Docker\n\n```sh\ndocker run --rm -i \\\n -e FRESHRSS_URL=https://rss.example.com \\\n -e FRESHRSS_USER=alice \\\n -e FRESHRSS_API_PASSWORD=... \\\n ghcr.io/ni-c/freshrss-mcp:latest\n```\n\nThe image is published for `linux/amd64` and `linux/arm64` with an SBOM and build\nprovenance. It runs as the unprivileged `node` user and carries no npm, so the\nonly thing in it is Node, the runtime dependencies and `dist/`.\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches freshrss-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"freshrss\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/freshrss-mcp\"],\n \"env\": { \"FRESHRSS_ALLOW_TOOLS\": \"essential\" },\n \"denyTools\": [\"delete_*\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://freshrss-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\n### Reading\n\n| Tool | Description |\n| ------------------- | ------------------------------------------------------------------------------------------- |\n| `get_user_info` | The authenticated account — a quick credential check. |\n| `list_feeds` | Every subscription with its category and unread count. |\n| `list_categories` | Categories (folders of feeds) and user labels (tags on articles). |\n| `get_unread_counts` | Total and per-feed/category unread counts, sorted. |\n| `list_articles` | Articles of a feed, category, label or built-in stream, with excerpts or bounded full text. |\n| `get_articles` | Full text of specific articles by id. |\n| `list_article_ids` | Ids only — the cheap way to collect a set for `mark_articles`. |\n| `export_opml` | All subscriptions as an OPML document. |\n\n### Writing\n\nNot registered when `FRESHRSS_READ_ONLY=true`.\n\n| Tool | Description | Confirmation |\n| -------------------------- | ----------------------------------------------------- | ------------ |\n| `mark_articles` | Set read state, star and labels on specific articles. | — |\n| `mark_all_as_read` | Mark a whole feed, category, label or stream as read. | yes |\n| `subscribe_feed` | Subscribe to a feed or website URL. | — |\n| `update_feed` | Rename a feed or move it to another category. | — |\n| `unsubscribe_feed` | Delete a feed and all of its stored articles. | yes |\n| `rename_category_or_label` | Rename a category or a user label. | — |\n| `delete_category_or_label` | Delete a category or a user label. | yes |\n| `import_opml` | Subscribe to every feed in an OPML document. | yes |\n\n### Structured output\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose:\n\n```jsonc\n{\n \"untrusted\": true,\n \"source\": \"freshrss\",\n \"articles\": [{ \"id\": \"1234\", \"title\": \"…\", \"read\": false, \"starred\": false }],\n \"continuation\": \"1699999999\",\n \"notes\": [\"…\"],\n}\n```\n\nEvery tool that reports feed content carries `untrusted: true` and\n`source: \"freshrss\"` as fields. This server has always said so in `notes` —\nprose in a list, which a client can read but not check — and the field is what\nmakes it checkable. Eight tools are without it, because their answer is entirely\nthis server's own words: ids it was given, a sentence built from the arguments,\nthe account it authenticates as.\n\nSix tools used to answer with a sentence (_\"Feed 9 deleted.\"_); they now answer\nwith the fields as well, and the sentence stays in the text block.\n`export_opml` returns `{opml}` rather than the document as the whole result: a\nschema whose root is a string is served to a 2025-era client rewritten as\n`{result: …}`, and `truncated` needs somewhere to live either way.\n\n### No search\n\nFreshRSS does not offer full-text search over its API — the Google Reader\nendpoints filter by stream, read state and date only. `list_articles` therefore\nhas no query parameter; narrow the result with `feed_id`/`category` and\n`since`/`until` and filter the returned articles yourself.\n\n## Not exposed, on purpose\n\n**No full-text search**, because FreshRSS offers none over the Google Reader API:\nits endpoints filter by stream, read state and date only. Narrow with `feed_id`,\n`category`, `since` and `until`, then filter the returned articles yourself. The\nsearch in the FreshRSS web interface has no API endpoint behind it.\n\n**No raw HTML.** Article bodies are converted to plain text and capped per article\nand per response, so one listing cannot bury everything else in the context.\n\n## Safety\n\n- **Article text is untrusted input.** Everything this server returns from\n FreshRSS was written by a third party on the internet, so responses that carry\n article text, titles or feed names are explicitly marked as data, never as\n instructions.\n- **A person is asked, not just told.** Where the client supports MCP\n elicitation, the five irreversible tools raise a real dialog that the model\n cannot answer on its behalf. A plain boolean could be set on the very first\n call, or be talked into it by text hidden in a feed. Where the client cannot\n show a dialog they fall back to a single-use token bound to the exact target,\n and say so rather than implying somebody approved. The messages deliberately\n never quote titles or names coming from the API. See\n [Asking a person](https://freshrss-mcp.ni-c.de/guide/approval).\n- **Response budgets.** FreshRSS returns up to 500 000 characters of HTML per\n article. Article text is converted to plain text, capped per article and\n against a per-response budget, and is opt-in in listings. The budget is\n charged for the markup that was read rather than for the text that came out,\n so it bounds the conversion work and not only the resulting context — markup\n that strips away to nothing is the expensive case, and it used to be free.\n The conversion itself is a single left-to-right scan, linear in the length of\n the article whatever the article contains.\n- **Credentials** are read once, removed from `process.env` afterwards and never\n written to disk. Requests never follow redirects, which would resend the\n authorization header to another host, and relaxed TLS validation is scoped to\n this connection instead of the whole process.\n- **Feed URLs are redacted.** FreshRSS stores HTTP-auth feeds as\n `https://user:password@host/feed`. The userinfo part is stripped before a feed\n URL reaches a tool result or the OPML export, so `list_feeds` cannot print the\n password of a paid or private feed into the transcript.\n- **`subscribe_feed` and `import_opml` refuse internal targets.** FreshRSS\n fetches those URLs server-side, which makes both tools an SSRF primitive\n reachable from text inside an article. Loopback and link-local addresses —\n including cloud metadata endpoints — are rejected, for the feed URL and for\n every `xmlUrl`/`htmlUrl` in an OPML document. Addresses are compared\n numerically, so an IPv4-mapped IPv6 literal such as `[::ffff:169.254.169.254]`\n is caught too, and a hostname is resolved before it is accepted. An OPML\n document is read the way an XML parser reads it, and what reaches FreshRSS is\n the document as checked — so the URL that was inspected is the URL that gets\n fetched. Private LAN addresses stay allowed, because self-hosted setups\n legitimately subscribe to feeds on their own network.\n- **`import_opml` refuses a ``.** No XML is parsed in this process, but\n the document is handed to FreshRSS, where a document type declaration is the\n carrier for entity-expansion and external-entity attacks. OPML never needs one.\n- `FRESHRSS_READ_ONLY=true` does not register the write tools at all rather than\n refusing them at call time.\n\nWhich tools ask a person: `mark_all_as_read`, `unsubscribe_feed`,\n`delete_category_or_label`, `import_opml` — and `mark_articles`, but only when it\nis about to mark something **read**. Starring, unstarring and labelling can all\nbe set back; which of those articles were unread cannot, and FreshRSS keeps no\nrecord of it.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[freshrss-mcp.ni-c.de](https://freshrss-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```sh\nnpm install\nnpm run lint && npm run build && npm test\nnpm run test:coverage\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for a throwaway FreshRSS to develop\nagainst. The full documentation lives at\n[freshrss-mcp.ni-c.de](https://freshrss-mcp.ni-c.de).\n\n## Releasing\n\n1. Move the `[Unreleased]` entries in [CHANGELOG.md](CHANGELOG.md) under the new\n version and bump `version` in `package.json`.\n2. `npm run lint && npm run build && npm run test:coverage`.\n3. Commit, then tag: `git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z`.\n\nThe tag triggers `release.yml`, which verifies the tag matches `package.json`,\npublishes to npm via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers)\nwith provenance (no token involved), creates the GitHub release from the CHANGELOG\nsection, and publishes the entry to the\n[MCP Registry](https://registry.modelcontextprotocol.io). If only the registry\nstep fails, fix it on `main` and re-run `mcp-registry.yml` by hand — never re-run\nthe tagged job, which would check out the old tree.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/freshrss-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n",
"bytes": 18453,
"sha": "6d5d301b10031d89212b37f53a68ade26b74a001773f799f7103ab24d902bd94",
"repo_slug": "ni-c/freshrss-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_freshrss_mcp_8f3e89c1/readme"
}