freshrss-mcp-server

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.