freshrss-mcp

# FreshRSS MCP Server A Model Context Protocol (MCP) server for [FreshRSS](https://www.freshrss.org/), 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 ```bash pip install freshrss-mcp ``` ### From source ```bash 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: ```bash FRESHRSS_URL=https://your-freshrss-instance.com FRESHRSS_EMAIL=your-email@example.com 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) ```bash # 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) ```bash # Activate virtual environment source venv/bin/activate # Run streamable HTTP server on port 8000 freshrss-mcp --http ``` **O…