FreshRSS MCP Server

A Model Context Protocol (MCP) server for FreshRSS, the self-hosted RSS feed aggregator. This server allows LLMs and other MCP clients to interact with your FreshRSS instance to manage feeds, read articles, and organize your RSS content.

Features

• 🔐 Authentication: Secure connection to your FreshRSS instance
• 📁 Folder Management: List and organize feeds in folders
• 📰 Article Reading: Fetch articles with advanced filtering options
• ✅ Article Management: Mark articles as read/unread, star/unstar
• 🏷️ Label System: Add labels to articles for organization
• 📡 Feed Management: Subscribe/unsubscribe from RSS feeds
• 📊 Unread Counts: Get unread statistics by feed and folder

Installation

Using pip

pip install freshrss-mcp

From source

git clone https://github.com/yourusername/freshrss-mcp.git
cd freshrss-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Configuration

Environment Variables

Create a .env file or set these environment variables:

FRESHRSS_URL=https://your-freshrss-instance.com
[email protected]
FRESHRSS_API_PASSWORD=your-api-password

Important: The FRESHRSS_API_PASSWORD is NOT your regular FreshRSS password. You need to:

1. Enable API access in FreshRSS Settings → Authentication
2. Set an API password in your Profile settings

Running the Server

Transport Modes

The FreshRSS MCP server supports multiple transport protocols:

1. Stdio Mode (Default - for Claude Desktop)

# Activate virtual environment
source venv/bin/activate

# Run with stdio transport (silent, for MCP clients)
freshrss-mcp

# Or explicitly
freshrss-mcp --stdio

2. HTTP Mode (for web integration)

# Activate virtual environment
source venv/bin/activate

# Run streamable HTTP server on port 8000
freshrss-mcp --http

Output:

INFO:freshrss_mcp.server:🚀 FreshRSS MCP Server starting on http://localhost:8000
INFO:freshrss_mcp.server:📋 13 MCP tools loaded for FreshRSS management
INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)

Available endpoints:

• 🌐 HTTP: http://localhost:8000
• 🔌 WebSocket: ws://localhost:8000/ws
• ❤️ Health Check: http://localhost:8000/health

3. Server-Sent Events Mode

freshrss-mcp --sse

4. Help

freshrss-mcp --help

Claude Desktop Configuration

For Stdio Mode (Recommended)

Add the FreshRSS MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "freshrss": {
      "command": "freshrss-mcp",
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_EMAIL": "[email protected]",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    }
  }
}

For HTTP Mode

{
  "mcpServers": {