A Model Context Protocol server for FreshRSS RSS reader
npm install mcp-freshrssA 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.
- 🔐 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/remove labels to articles for organization
- 📡 Feed Management: Subscribe/unsubscribe from RSS feeds
- 📊 Unread Counts: Get unread statistics by feed and folder
- 🌐 Multiple Transports: Supports stdio, Streamable HTTP, and SSE
``bash`
npm install -g mcp-freshrss
`bash`
git clone https://github.com/yourusername/mcp-freshrss.git
cd mcp-freshrss
npm install
npm run build
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
The FreshRSS MCP server supports multiple transport protocols:
#### 1. Stdio Mode (Default - for Claude Desktop)
`bashRun with stdio transport (silent, for MCP clients)
mcp-freshrss
#### 2. Streamable HTTP Mode (Recommended for web integration)
`bash
Run Streamable HTTP server on default port 8000
mcp-freshrss --httpRun on custom port
mcp-freshrss --http --port 3000Or use PORT environment variable
PORT=3000 mcp-freshrss --http
`Available endpoints:
- 🌐 Streamable HTTP:
POST/GET/DELETE http://localhost:8000/mcp
- 🔌 SSE (backwards compat): GET http://localhost:8000/sse
- 📨 Messages: POST http://localhost:8000/messages
- ❤️ Health Check: GET http://localhost:8000/health#### 3. Deprecated SSE Mode
`bash
mcp-freshrss --sse --port 8000
`#### 4. Help
`bash
mcp-freshrss --help
`$3
For Stdio Mode (Recommended):
Add the FreshRSS MCP server to your Claude Desktop configuration (
~/Library/Application Support/Claude/claude_desktop_config.json on macOS):`json
{
"mcpServers": {
"freshrss": {
"command": "mcp-freshrss",
"env": {
"FRESHRSS_URL": "https://your-freshrss-instance.com",
"FRESHRSS_EMAIL": "your-email@example.com",
"FRESHRSS_API_PASSWORD": "your-api-password"
}
}
}
}
`Or if running from source:
`json
{
"mcpServers": {
"freshrss": {
"command": "node",
"args": ["/path/to/mcp-freshrss/dist/index.js"],
"env": {
"FRESHRSS_URL": "https://your-freshrss-instance.com",
"FRESHRSS_EMAIL": "your-email@example.com",
"FRESHRSS_API_PASSWORD": "your-api-password"
}
}
}
}
`Available Tools
$3
####
freshrss_list_foldersList all folders/categories in your FreshRSS instance.
####
freshrss_list_subscriptionsList all subscribed feeds with their folder assignments.
$3
####
freshrss_get_articlesFetch articles with various filtering options.
| Parameter | Type | Description |
|-----------|------|-------------|
|
folder | string | Filter by folder name |
| feed_url | string | Filter by specific feed URL |
| feed_id | string | Filter by specific feed ID |
| show_read | boolean | Include read articles (default: true) |
| starred_only | boolean | Only show starred articles (default: false) |
| count | number | Number of articles to fetch (default: 50, max ~1000) |
| continuation | string | Continuation token for pagination |####
freshrss_get_unread_countGet unread article counts organized by feed and folder.
$3
####
freshrss_mark_readMark one or more articles as read.
`json
{
"article_ids": ["tag:google.com,2005:reader/item/..."]
}
`####
freshrss_mark_unreadMark one or more articles as unread.
####
freshrss_star_articleStar one or more articles.
####
freshrss_unstar_articleUnstar one or more articles.
####
freshrss_add_labelAdd a label to one or more articles.
`json
{
"article_ids": ["tag:google.com,2005:reader/item/..."],
"label": "Important"
}
`####
freshrss_remove_labelRemove a label from one or more articles.
$3
####
freshrss_subscribeSubscribe to a new RSS feed.
`json
{
"feed_url": "https://example.com/feed.xml",
"title": "Example Blog",
"folder": "Tech"
}
`####
freshrss_unsubscribeUnsubscribe from a feed.
`json
{
"feed_url": "https://example.com/feed.xml"
}
`Development
$3
`bash
Clone the repository
git clone https://github.com/yourusername/mcp-freshrss.git
cd mcp-freshrssInstall dependencies
npm installCopy environment example
cp .env.example .env
Edit .env with your FreshRSS credentials
Build the project
npm run buildRun in development mode
npm run dev
`$3
-
npm run build - Build TypeScript to JavaScript
- npm run dev - Run in development mode with tsx
- npm run watch - Watch mode for TypeScript compilation
- npm run lint - Run ESLint
- npm start` - Run the built serverThis MCP server implements the Google Reader API as supported by FreshRSS:
- Authentication via ClientLogin
- Stream contents for article fetching
- Edit tag operations for marking read/starred
- Subscription management
- Tag/folder listing
- "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
- Use pagination with continuation tokens for large article lists
- Filter by folder or feed to reduce response size
- Set appropriate count values (max ~1000 per request)
MIT License - see LICENSE file for details.
- FreshRSS for the excellent RSS reader
- Model Context Protocol for the MCP specification