freshrss-mcp

Сервер для Model Context Protocol для FreshRSS, самоуправляемого агрегатора RSS и Atom фидов.

Он использует API, совместимый с Google Reader, который FreshRSS предоставляет по адресу /api/greader.php, и скрывает особенности этого API за аргументами инструментов, которые ассистент может реально использовать: числовые идентификаторы фидов, имена категорий и меток, даты в формате ISO и десятичные идентификаторы статей вместо идентификаторов потоков вида user/-/state/com.google/… и шестнадцатеричных тегов элементов.

📖 Полная документация: freshrss-mcp.ni-c.de

Требования

• Node.js 22 или новее

• Экземпляр FreshRSS (разработан для версии 1.29) с

  • включенным API: Настройки → Аутентификация → "Allow API access"

  • установленным API-паролем для пользователя: Настройки → Профиль → API management. Это отдельный пароль, отличный от пароля для входа в веб-интерфейс.

Related MCP server: Conduit

Конфигурация

Сервер запускается без учетных данных, поэтому его инструменты остаются перечисляемыми; каждый вызов завершается ошибкой с этими инструкциями по настройке.

Claude Code

claude mcp add freshrss -- npx -y @ni-c/freshrss-mcp

Claude Desktop

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": {
        "FRESHRSS_URL": "https://rss.example.com",
        "FRESHRSS_USER": "alice",
        "FRESHRSS_API_PASSWORD": "…"
      }
    }
  }
}

Codex

[mcp_servers.freshrss]
command = "npx"
args = ["-y", "@ni-c/freshrss-mcp"]
env = { FRESHRSS_URL = "https://rss.example.com", FRESHRSS_USER = "alice", FRESHRSS_API_PASSWORD = "…" }

Инструменты

Чтение

Запись

Не регистрируются, если FRESHRSS_READ_ONLY=true.

Поиск отсутствует

FreshRSS не предоставляет полнотекстовый поиск через свой API — конечные точки Google Reader фильтруют только по потоку, состоянию прочтения и дате. Поэтому list_articles не имеет параметра запроса; сузьте результат с помощью feed_id/category и since/until и отфильтруйте полученные статьи самостоятельно.

Безопасность

• Текст статей считается ненадежным вводом. Все, что этот сервер возвращает из FreshRSS, было написано третьей стороной в интернете, поэтому ответы, содержащие текст статей, заголовки или имена фидов, явно помечаются как данные, а не как инструкции.

• Деструктивные инструменты требуют двух шагов. Они возвращают одноразовый токен подтверждения, привязанный к конкретной цели; второй вызов должен содержать его. Простой булевый флаг можно было бы установить при первом вызове или склонить к этому текст, скрытый в фиде. Сообщения подтверждения намеренно никогда не цитируют заголовки или имена, полученные из API.

• Бюджеты ответов. FreshRSS возвращает до 500 000 символов HTML на одну статью. Текст статьи преобразуется в обычный текст, ограничивается на статью и на общий бюджет ответа, и является опциональным в списках.

• Учетные данные читаются один раз, затем удаляются из process.env и никогда не записываются на диск. Запросы никогда не следуют перенаправлениям, которые могли бы повторно отправить заголовок авторизации другому хосту, а ослабленная проверка TLS ограничена этим соединением, а не всем процессом.

• URL фидов редактируются. FreshRSS хранит фиды с HTTP-аутентификацией как https://user:password@host/feed. Часть с информацией о пользователе удаляется, прежде чем URL фида попадет в результат инструмента или экспорт OPML, поэтому list_feeds не может вывести пароль платного или приватного фида в транскрипт.

• subscribe_feed отклоняет внутренние цели. FreshRSS извлекает URL на стороне сервера, что делает инструмент примитивом SSRF, доступным из текста внутри статьи. Адреса loopback и link-local, включая конечные точки метаданных облака, отклоняются. Адреса частных локальных сетей остаются разрешенными, потому что в самоуправляемых установках законно подписываются на фиды в своей собственной сети.

• import_opml отклоняет <!DOCTYPE>. В этом процессе не выполняется разбор XML, но документ передается FreshRSS, где объявление типа документа является носителем атак расширения сущностей и внешних сущностей. OPML никогда не нуждается в нем.

• FRESHRSS_READ_ONLY=true не регистрирует инструменты записи вообще, а не отклоняет их во время вызова.

Какие инструменты защищены токеном подтверждения: mark_all_as_read, unsubscribe_feed, delete_category_or_label и import_opml. mark_articles намеренно не защищен — вызывающий явно указывает каждую из не более 100 статей, и каждое поле можно сбросить — но он объявлен деструктивным, поэтому клиент все равно может запросить подтверждение.

Контейнер

docker run --rm -i \
  -e FRESHRSS_URL=https://rss.example.com \
  -e FRESHRSS_USER=alice \
  -e FRESHRSS_API_PASSWORD=... \
  ghcr.io/ni-c/freshrss-mcp:latest

Образ публикуется для linux/amd64 и linux/arm64 с SBOM и происхождением сборки. Он работает как непривилегированный пользователь node и не содержит npm, так что в нем есть только Node, зависимости времени выполнения и dist/.

Разработка

npm install
npm run lint && npm run build && npm test
npm run test:coverage

См. CONTRIBUTING.md для получения одноразового FreshRSS для разработки. Полная документация находится по адресу freshrss-mcp.ni-c.de.

Релиз

1. Перенесите записи [Unreleased] в CHANGELOG.md под новую версию и увеличьте version в package.json.

2. npm run lint && npm run build && npm run test:coverage.

3. Зафиксируйте, затем создайте тег: git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z.

Тег запускает release.yml, который проверяет соответствие тега package.json, публикует в npm через Trusted Publishing с подтверждением происхождения (без токена), создает релиз на GitHub из раздела CHANGELOG и публикует запись в MCP Registry. Если только шаг реестра завершается ошибкой, исправьте его в main и повторно запустите mcp-registry.yml вручную — никогда не перезапускайте задачу с тегом, так как это проверит старую версию дерева.

Лицензия

MIT