freshrss-mcp

Un servidor Model Context Protocol para FreshRSS, el agregador de feeds RSS y Atom autoalojado.

Habla la API compatible con Google Reader que FreshRSS expone en /api/greader.php, y oculta las peculiaridades de esa API detrás de argumentos de herramientas que un asistente puede usar realmente: identificadores de feed numéricos, nombres de categorías y etiquetas, fechas ISO e identificadores de artículo decimales en lugar de identificadores de flujo user/-/state/com.google/… y etiquetas de elementos hexadecimales.

📖 Documentación completa: freshrss-mcp.ni-c.de

Requisitos

• Node.js 22 o superior

• Una instancia de FreshRSS (desarrollada contra 1.29) con

  • la API habilitada: Ajustes → Autenticación → "Permitir acceso a la API"

  • una contraseña de API configurada para el usuario: Ajustes → Perfil → Gestión de la API. Esta es una contraseña separada de la de inicio de sesión web.

Related MCP server: Conduit

Configuración

El servidor arranca sin credenciales para que sus herramientas se puedan listar; cada llamada entonces falla con estas instrucciones de configuración.

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 = "…" }

Herramientas

Lectura

Escritura

No registradas cuando FRESHRSS_READ_ONLY=true.

Sin búsqueda

FreshRSS no ofrece búsqueda de texto completo a través de su API: los endpoints de Google Reader filtran solo por flujo, estado de lectura y fecha. list_articles por lo tanto no tiene parámetro de consulta; restringe el resultado con feed_id/category y since/until y filtra los artículos devueltos tú mismo.

Seguridad

• El texto de los artículos es entrada no confiable. Todo lo que este servidor devuelve de FreshRSS fue escrito por un tercero en internet, por lo que las respuestas que contienen texto de artículos, títulos o nombres de feeds se marcan explícitamente como datos, nunca como instrucciones.

• Las herramientas destructivas son de dos pasos. Devuelven un token de confirmación de un solo uso vinculado al objetivo exacto; la segunda llamada debe llevarlo. Un booleano plano podría establecerse en la primera llamada, o ser inducido por texto oculto en un feed. Los mensajes de confirmación deliberadamente nunca citan títulos o nombres provenientes de la API.

• Presupuestos de respuesta. FreshRSS devuelve hasta 500 000 caracteres de HTML por artículo. El texto del artículo se convierte a texto plano, con un límite por artículo y contra un presupuesto por respuesta, y es opcional en los listados.

• Las credenciales se leen una vez, se eliminan de process.env después y nunca se escriben en disco. Las solicitudes nunca siguen redirecciones, que reenviarían el encabezado de autorización a otro host, y la validación TLS relajada se limita a esta conexión en lugar de todo el proceso.

• Las URLs de los feeds son censuradas. FreshRSS almacena los feeds con autenticación HTTP como https://user:password@host/feed. La parte de información de usuario se elimina antes de que una URL de feed llegue a un resultado de herramienta o a la exportación OPML, por lo que list_feeds no puede imprimir la contraseña de un feed de pago o privado en la transcripción.

• subscribe_feed rechaza destinos internos. FreshRSS obtiene la URL del lado del servidor, lo que convierte la herramienta en un primitivo SSRF accesible desde el texto dentro de un artículo. Las direcciones de loopback y link-local — incluyendo los endpoints de metadatos de servicios cloud — son rechazadas. Las direcciones LAN privadas siguen permitidas, porque las instalaciones autoalojadas legítimamente se suscriben a feeds en su propia red.

• import_opml rechaza un <!DOCTYPE>. No se analiza XML en este proceso, pero el documento se entrega a FreshRSS, donde una declaración de tipo de documento es el vehículo para ataques de expansión de entidades y entidades externas. OPML nunca necesita una.

• FRESHRSS_READ_ONLY=true no registra en absoluto las herramientas de escritura, en lugar de rechazarlas en el momento de la llamada.

Qué herramientas están protegidas por un token de confirmación: mark_all_as_read, unsubscribe_feed, delete_category_or_label e import_opml. mark_articles deliberadamente no está protegida — el llamante nombra cada uno de hasta 100 artículos explícitamente y cada campo puede revertirse — pero se declara destructiva, por lo que un cliente aún puede solicitarla.

Contenedor

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

La imagen se publica para linux/amd64 y linux/arm64 con un SBOM y procedencia de compilación. Se ejecuta como el usuario no privilegiado node y no lleva npm, por lo que lo único que contiene es Node, las dependencias de tiempo de ejecución y dist/.

Desarrollo

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

Consulta CONTRIBUTING.md para obtener un FreshRSS desechable para desarrollar. La documentación completa está en freshrss-mcp.ni-c.de.

Publicación

1. Mover las entradas [Unreleased] en CHANGELOG.md debajo de la nueva versión y aumentar version en package.json.

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

3. Confirmar y luego etiquetar: git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z.

La etiqueta activa release.yml, que verifica que la etiqueta coincide con package.json, publica en npm mediante Trusted Publishing con procedencia (sin token involucrado), crea el lanzamiento de GitHub desde la sección de CHANGELOG y publica la entrada en el MCP Registry. Si solo falla el paso del registro, corrígelo en main y vuelve a ejecutar mcp-registry.yml manualmente — nunca vuelvas a ejecutar el trabajo etiquetado, porque haría checkout del árbol antiguo.

Licencia

MIT