FreshRSS MCP Server (Node.js)

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/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

Installation

$3

``bash
npm install -g mcp-freshrss
`

$3

`bash
git clone https://github.com/yourusername/mcp-freshrss.git
cd mcp-freshrss
npm install
npm run build
`

Configuration

$3

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

Usage

$3

The FreshRSS MCP server supports multiple transport protocols:

#### 1. Stdio Mode (Default - for Claude Desktop)

`bash


Run with stdio transport (silent, for MCP clients)

mcp-freshrss

Or explicitly

mcp-freshrss --stdio
`

#### 2. Streamable HTTP Mode (Recommended for web integration)

`bash


Run Streamable HTTP server on default port 8000

mcp-freshrss --http

Run on custom port

mcp-freshrss --http --port 3000

Or 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_folders

List all folders/categories in your FreshRSS instance.

#### freshrss_list_subscriptions

List all subscribed feeds with their folder assignments.

$3

#### freshrss_get_articles

Fetch 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_count

Get unread article counts organized by feed and folder.

$3

#### freshrss_mark_read

Mark one or more articles as read.

`json
{
"article_ids": ["tag:google.com,2005:reader/item/..."]
}
`

#### freshrss_mark_unread

Mark one or more articles as unread.

#### freshrss_star_article

Star one or more articles.

#### freshrss_unstar_article

Unstar one or more articles.

#### freshrss_add_label

Add a label to one or more articles.

`json
{
"article_ids": ["tag:google.com,2005:reader/item/..."],
"label": "Important"
}
`

#### freshrss_remove_label

Remove a label from one or more articles.

$3

#### freshrss_subscribe

Subscribe to a new RSS feed.

`json
{
"feed_url": "https://example.com/feed.xml",
"title": "Example Blog",
"folder": "Tech"
}
`

#### freshrss_unsubscribe

Unsubscribe 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-freshrss

Install dependencies

npm install

Copy environment example

cp .env.example .env

Edit .env with your FreshRSS credentials

Build the project

npm run build

Run 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 server

API Implementation

This 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

Troubleshooting

$3

- "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

$3

- 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)

License

MIT License - see LICENSE file for details.

Acknowledgments

- FreshRSS for the excellent RSS reader
- Model Context Protocol for the MCP specification