What is Freshrss Server

FreshRSS MCP Server is a Model Context Protocol server designed to enable interaction with FreshRSS feeds using the Fever API. It allows AI assistants to manage RSS feeds effectively and provides a seamless integration for accessing various feed functionalities.

Use cases

This server can be employed to list RSS feed subscriptions, browse feeds, retrieve unread items, mark items as read or unread, and specific feed item retrieval, making it suitable for developers and users wanting to enhance their RSS feed management through automation and AI assistance.

How to use

To use the FreshRSS MCP Server, set up environment variables for the FreshRSS API details, and configure the server in the desktop application by specifying the command to run the server along with necessary environment variables. Make sure to build the server before running it.

Key features

Key features include listing feeds, fetching unread items, marking items as read/unread, retrieving items from specific feeds, marking entire feeds as read, and acquiring items by their IDs. These functionalities enhance the user’s ability to manage their RSS feed consumption efficiently.

Where to use

This MCP server can be utilized with applications like Claude Desktop and Cline MCP integration, allowing users to integrate FreshRSS functionality directly into their current workflow, automating RSS feed interactions within AI-assisted environments.

FreshRSS MCP Server

A Model Context Protocol server for interacting with FreshRSS feeds via the Fever API.

This TypeScript-based MCP server allows AI assistants to interact with your FreshRSS instance, enabling them to:

• List and browse your RSS feeds
• Fetch unread items
• Mark items as read/unread
• Get items from specific feeds

Features

Tools

• list_feeds - List all feed subscriptions
• get_feed_groups - Get feed groups
• get_unread - Get unread items
• get_feed_items - Get items from a specific feed
• mark_item_read - Mark an item as read
• mark_item_unread - Mark an item as unread
• mark_feed_read - Mark all items in a feed as read
• get_items - Get specific items by their IDs

Requirements

• A running FreshRSS instance with API access enabled
• API endpoint URL, username, and password for your FreshRSS instance

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Environment Variables

You need to set the following environment variables:

• FRESHRSS_API_URL: URL to your FreshRSS instance (e.g., “https://rss.example.com”)
• FRESHRSS_USERNAME: Your FreshRSS username
• FRESHRSS_PASSWORD: Your FreshRSS password

Installation

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "freshrss": {
      "command": "node",
      "args": [
        "/path/to/freshrss-server/build/index.js"
      ],
      "env": {
        "FRESHRSS_API_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_PASSWORD": "your-password"
      }
    }
  }
}

For Cline MCP integration, add to your MCP settings:

{
  "mcpServers": {
    "freshrss": {
      "command": "node",
      "args": [
        "/path/to/freshrss-server/build/index.js"
      ],
      "env": {
        "FRESHRSS_API_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_PASSWORD": "your-password"
      }
    }
  }
}

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Security Note

This server requires your FreshRSS credentials. For security:

• Never commit your credentials to version control
• Always use environment variables for sensitive information
• Consider using a dedicated FreshRSS account with appropriate permissions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.