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

From npm

npm install -g mcp-freshrss

From source

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

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

Usage

Transport Modes

The FreshRSS MCP server supports multiple transport protocols:

1. Stdio Mode (Default - for Claude Desktop)

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

# Or explicitly
mcp-freshrss --stdio

2. Streamable HTTP Mode (Recommended for web integration)

# 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

mcp-freshrss --sse --port 8000

4. Help

mcp-freshrss --help

Claude Desktop Configuration

For Stdio Mode (Recommended):

Add the FreshRSS MCP server to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Or if running from source:

{
  "mcpServers": {
    "freshrss": {
      "command": "node",
      "args": ["/path/to/mcp-freshrss/dist/index.js"],
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_EMAIL": "[email protected]",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    }
  }
}

Available Tools

Folder Management

freshrss_list_folders

List all folders/categories in your FreshRSS instance.

freshrss_list_subscriptions

List all subscribed feeds with their folder assignments.

Article Reading

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.

Article Management

freshrss_mark_read

Mark one or more articles as read.

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

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

freshrss_remove_label

Remove a label from one or more articles.

Feed Management

freshrss_subscribe

Subscribe to a new RSS feed.

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

freshrss_unsubscribe

Unsubscribe from a feed.

{
  "feed_url": "https://example.com/feed.xml"
}

Development

Setup

# 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

Scripts

• 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

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