FreshRSS MCP Server
Allows management of RSS feeds and articles through a FreshRSS instance, including subscribing to feeds, reading and marking articles, and organizing them into folders and labels.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreshRSS MCP Server show unread articles from Tech folder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: FreshRSS MCP Server
Installation
Using pip
pip install freshrss-mcpFrom 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
FRESHRSS_EMAIL=your-email@example.com
FRESHRSS_API_PASSWORD=your-api-passwordImportant: The FRESHRSS_API_PASSWORD is NOT your regular FreshRSS password. You need to:
Enable API access in FreshRSS Settings → Authentication
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 --stdio2. HTTP Mode (for web integration)
# Activate virtual environment
source venv/bin/activate
# Run streamable HTTP server on port 8000
freshrss-mcp --httpOutput:
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 --sse4. Help
freshrss-mcp --helpClaude 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": "your-email@example.com",
"FRESHRSS_API_PASSWORD": "your-api-password"
}
}
}
}For HTTP Mode
{
"mcpServers": {
"freshrss": {
"command": "freshrss-mcp",
"args": ["--http"],
"env": {
"FRESHRSS_URL": "https://your-freshrss-instance.com",
"FRESHRSS_EMAIL": "your-email@example.com",
"FRESHRSS_API_PASSWORD": "your-api-password"
}
}
}
}Available Tools
Authentication
freshrss_authenticate
Authenticate with your FreshRSS instance. Can use environment variables or explicit parameters.
# Using environment variables
await freshrss_authenticate()
# Using explicit parameters
await freshrss_authenticate({
"base_url": "https://freshrss.example.com",
"email": "user@example.com",
"api_password": "your-api-password"
})Folder Management
freshrss_list_folders
List all folders/categories in your FreshRSS instance.
result = await freshrss_list_folders()
# Returns: {"folders": [{"name": "Tech", "id": "user/-/label/Tech", "type": "folder"}], "count": 1}freshrss_list_subscriptions
List all subscribed feeds with their folder assignments.
result = await freshrss_list_subscriptions()
# Returns detailed subscription information including foldersArticle Reading
freshrss_get_articles
Fetch articles with various filtering options.
# Get unread articles from all feeds
await freshrss_get_articles({"show_read": false, "count": 50})
# Get articles from specific folder
await freshrss_get_articles({"folder": "Tech", "count": 20})
# Get starred articles
await freshrss_get_articles({"starred_only": true})
# Get articles from specific feed
await freshrss_get_articles({"feed_url": "https://example.com/feed.xml"})
# Pagination
await freshrss_get_articles({"count": 50, "continuation": "continuation_token"})freshrss_get_unread_count
Get unread article counts organized by feed and folder.
result = await freshrss_get_unread_count()
# Returns total unread count plus breakdowns by feed and folderArticle Management
freshrss_mark_read
Mark one or more articles as read.
await freshrss_mark_read({
"article_ids": ["tag:google.com,2005:reader/item/..."]
})freshrss_mark_unread
Mark one or more articles as unread.
await freshrss_mark_unread({
"article_ids": ["tag:google.com,2005:reader/item/..."]
})freshrss_star_article
Star one or more articles.
await freshrss_star_article({
"article_ids": ["tag:google.com,2005:reader/item/..."]
})freshrss_unstar_article
Unstar one or more articles.
await freshrss_unstar_article({
"article_ids": ["tag:google.com,2005:reader/item/..."]
})freshrss_add_label
Add a label to one or more articles.
await freshrss_add_label({
"article_ids": ["tag:google.com,2005:reader/item/..."],
"label": "Important"
})Feed Management
freshrss_subscribe
Subscribe to a new RSS feed.
# Basic subscription
await freshrss_subscribe({
"feed_url": "https://example.com/feed.xml"
})
# With custom title and folder
await freshrss_subscribe({
"feed_url": "https://example.com/feed.xml",
"title": "Example Blog",
"folder": "Tech"
})freshrss_unsubscribe
Unsubscribe from a feed.
await freshrss_unsubscribe({
"feed_url": "https://example.com/feed.xml"
})Example Usage
Here's a complete example of using the FreshRSS MCP server:
# 1. Authenticate
await freshrss_authenticate()
# 2. List folders
folders = await freshrss_list_folders()
print(f"You have {folders['count']} folders")
# 3. Get unread counts
counts = await freshrss_get_unread_count()
print(f"Total unread: {counts['total_unread']}")
# 4. Fetch unread articles from Tech folder
articles = await freshrss_get_articles({
"folder": "Tech",
"show_read": false,
"count": 10
})
# 5. Mark first article as read
if articles['articles']:
await freshrss_mark_read({
"article_ids": [articles['articles'][0]['id']]
})
# 6. Star an interesting article
await freshrss_star_article({
"article_ids": [articles['articles'][1]['id']]
})Development
Quick Start in Virtual Environment
# Clone and setup
git clone https://github.com/yourusername/freshrss-mcp.git
cd freshrss-mcp
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .
# Configure environment
cp .env.example .env
# Edit .env with your FreshRSS credentials
# Test the installation
python test_direct.py
# Run HTTP server
freshrss-mcp --httpRunning Tests
pytest tests/Code Style
This project uses Black for code formatting and Ruff for linting:
black src/
ruff check src/Development Commands
# Test all transport modes
freshrss-mcp --help
freshrss-mcp --stdio # For MCP clients
freshrss-mcp --http # HTTP server on port 8000
freshrss-mcp --sse # Server-Sent Events
# Test API client directly
python test_direct.py
# Install development dependencies
pip install -e ".[dev]"API Implementation
This MCP server implements the Google Reader API as supported by FreshRSS. The implementation includes:
Authentication via ClientLogin
Stream contents for article fetching
Edit tag operations for marking read/starred
Subscription management
Tag/folder listing
Troubleshooting
Authentication Issues
"No auth token in response": Make sure you're using the API password, not your regular password
HTTP 404 errors: Check that your FreshRSS URL is correct and includes the protocol (https://)
API not enabled: Ensure API access is enabled in FreshRSS Settings → Authentication
Performance Tips
Use pagination with
continuationtokens for large article listsFilter by folder or feed to reduce response size
Set appropriate
countvalues (max ~1000 per request)
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request
License
MIT License - see LICENSE file for details
Acknowledgments
FreshRSS for the excellent RSS reader
Model Context Protocol for the MCP specification
The FreshRSS community for API documentation
Available Tools
18 toolsfreshrss_add_labelC
Add label to articles.
Inputs: params (required). Returns: result
freshrss_authenticateA
Authenticate with FreshRSS instance and save credentials to environment for subsequent calls.
Uses provided parameters or falls back to environment variables:
FRESHRSS_URL
FRESHRSS_EMAIL
FRESHRSS_API_PASSWORD
Inputs: params (required). Returns: result
freshrss_get_article_detailA
Get full content for specific articles by ID.
Use after scanning headlines to deep-dive into interesting articles. Max 10 articles per call to control token usage.
Inputs: params (required). Returns: result
freshrss_get_articlesC
Fetch articles with various filters.
Inputs: params (required). Returns: result
freshrss_get_digest_compactA
Get an ultra-compact category-balanced digest as plain text.
Returns ~10 tokens per article vs ~100 for JSON format. Each line: [short_id] Title (Feed) Grouped by category with counts.
Designed for agent curation workflows where token efficiency matters. After selecting articles, use mark_stream_read + mark_unread to keep only your picks.
Inputs: params (required). Returns: result
freshrss_get_diverse_digestA
Get a category-balanced digest of recent unread articles.
Fetches N articles from EACH category to ensure topic diversity. Returns headlines only (token-efficient). Use get_article_detail to deep-dive into selected articles.
This is the primary tool for daily curation — ensures you see security, business, world news, etc., not just AI/ML.
Inputs: params (required). Returns: result
freshrss_get_headlinesA
Get article headlines only — ultra token-efficient.
Returns only: id, title, feed_title, folder, published, url. ~10x fewer tokens than get_articles. Use this for scanning/triage, then call get_article_detail for articles you want to read in full.
Inputs: params (required). Returns: result
freshrss_get_tokenA
Get edit token for write operations. Usually called automatically when needed.
Inputs: no named parameters. Returns: result
freshrss_get_unread_countA
Get unread counts by feed and folder.
Inputs: no named parameters. Returns: result
freshrss_list_foldersB
List all folders/categories/tags in FreshRSS.
Inputs: no named parameters. Returns: result
freshrss_list_subscriptionsA
List all subscribed feeds with their folders.
Inputs: no named parameters. Returns: result
freshrss_mark_readC
Mark articles as read.
Inputs: params (required). Returns: result
freshrss_mark_stream_readA
Mark all articles in a stream/folder as read in one call.
MUCH more efficient than marking individual articles. Use 'all' to mark everything, or a folder name like 'tech', 'ML', 'security'.
Common pattern: mark_stream_read(all) then mark_unread([5 keeper IDs]).
Inputs: params (required). Returns: result
freshrss_mark_unreadC
Mark articles as unread.
Inputs: params (required). Returns: result
freshrss_star_articleC
Star articles.
Inputs: params (required). Returns: result
freshrss_subscribeB
Subscribe to a new feed.
Inputs: params (required). Returns: result
freshrss_unstar_articleC
Unstar articles.
Inputs: params (required). Returns: result
freshrss_unsubscribeB
Unsubscribe from a feed.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clearly distinct purposes, especially the write operations (mark_read vs mark_stream_read, star vs unstar). However, the five article retrieval tools (get_articles, get_headlines, get_article_detail, get_diverse_digest, get_digest_compact) overlap considerably; their descriptions distinguish use cases well, but an agent could still confuse get_diverse_digest with get_digest_compact or get_articles with get_headlines.
All tools follow a consistent freshrss_verb_noun pattern, e.g., list_folders, subscribe, mark_read, get_article_detail. Even compound nouns like stream_read and digest_compact are consistently formatted with underscores. The naming is predictable and uniform across the entire set.
18 tools is slightly above the ideal range but justified for a full-featured RSS reader covering authentication, subscription management, article retrieval, read/unread/star/label operations, and summaries. A few tools like get_token are auxiliary and could be implicit, but the count is not excessive for the scope.
The surface covers core FreshRSS workflows well: authentication, subscribe/unsubscribe, listing folders/subscriptions, fetching articles with various token-efficiency levels, and marking read/unread/starred/labeled. Minor gaps include no folder creation/deletion/renaming and no subscription update (e.g., moving feeds between folders), but these are not critical for typical agent curation workflows.
Maintenance
Related MCP Connectors
RSS & Atom feed manager with full-text search, AI curation, and remote MCP endpoint.
Read, search and organize the RSS feeds you follow in Feeder. Tool calls need Feeder Plus.
Track and browse RSS feeds with ease. Fetch the latest entries from any feed URL and extract full…
Your feeds inside your AI. Read and search the articles of the RSS feeds, YouTube channels, podcasts and Google News searches you follow. On Plus and Pro, also save, tag, highlight and add notes. OAuth sign-in, every FeedNest plan.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with RSS readers that support the FreshRSS API through natural language. Allows users to manage and query their RSS feeds and articles via LLM conversations.7MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with FreshRSS RSS feed readers through the Google Reader compatible API. Supports feed management, article reading/searching, and marking articles as read or starred.-
- AlicenseBqualityDmaintenanceEnables interaction with FreshRSS instances through the Google Reader API. Supports managing articles, feeds, folders, labels, and OPML import/export for RSS feed aggregation through natural language.2734 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with FreshRSS feeds via the Fever API, allowing listing feeds, fetching unread items, marking items as read/unread, and managing feed subscriptions.86 npm10MIT