freshrss-mcp-server

An MCP (Model Context Protocol) server implementation to interact with your FreshRSS server, using the Google Reader API.

Features

• Full FreshRSS Integration: Access all major Google Reader API features
• Simple Authentication: Direct FreshRSS API authentication
• Subscription Management: Subscribe, unsubscribe, import/export OPML
• Content Reading: Fetch reading lists, starred items, specific feeds, and categories
• Item Operations: Mark as read/unread, star/unstar, add/remove labels
• Category Management: List, rename, and delete categories
• Persistent Storage: SQLite database for auth tokens and sync state at ~/.freshrss/
• Session Management: Login/logout with complete data clearing
• Claude Desktop Ready: Works seamlessly with Claude Desktop as a local MCP server

Installation

# Clone the repository
git clone https://github.com/nitinthewiz/freshrss-mcp-server.git
cd freshrss-mcp-server

# Install in editable mode with all dependencies
pip install -e .

# For development (includes testing and linting tools)
pip install -e ".[dev]"

Configuration

Claude Desktop

Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "freshrss": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/freshrss-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/freshrss-mcp-server"
      }
    }
  }
}

Environment Variables (Optional)

All configuration is optional with sensible defaults:

# Server Transport ("stdio" or "streamable-http")
MCP_TRANSPORT=stdio
MCP_HOST=127.0.0.1    # For HTTP transport
MCP_PORT=8000         # For HTTP transport

# Database (default: ~/.freshrss/freshrss.db)
DATABASE_PATH=/path/to/custom/freshrss.db

# Logging
DEBUG=false
LOG_LEVEL=INFO

# HTTP Client Settings
HTTP_TIMEOUT=30
HTTP_MAX_RETRIES=3
HTTP_RETRY_DELAY=1.0
HTTP_BACKOFF_FACTOR=2.0

# Cache Settings
CACHE_SUBSCRIPTION_TTL=300
CACHE_UNREAD_COUNT_TTL=30

Usage

Running the Server

stdio Mode (Default - for Claude Desktop)

# Using Python directly
python -m src.main

# Using FastMCP CLI
fastmcp run src/main.py:mcp

Streamable HTTP Mode (for HTTP-based MCP clients)

This mode supports the MCP specification 2025-03-26 Streamable HTTP transport, enabling HTTP-based MCP clients to connect.

# Using environment variables
MCP_TRANSPORT=streamable-http python -m src.main

# With custom host/port
MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8080 python -m src.main

# Using FastMCP CLI
fastmcp run src/main.py:mcp --transport streamable-http --port 8000

The server will be available at http://127.0.0.1:8000/mcp (or your configured host:port).

Development Mode (with MCP Inspector)

# Opens web UI for testing tools interactively
fastmcp dev src/main.py:mcp

Available MCP Tools

Authentication

• login_to_freshrss(server_url, username, password) - Login and store credentials
  • Supports flexible URL formats (base URL, with /i/, or /api/greader.php)
• logout_from_freshrss() - Logout and clear all data
• get_freshrss_user_info() - Get current user info
• check_freshrss_session() - Validate session

Subscriptions

• list_freshrss_subscriptions() - List all feeds
• subscribe_to_feed(feed_url, title?, category?) - Subscribe to a feed
• unsubscribe_from_feed(feed_id) - Unsubscribe from a feed
• quick_subscribe_to_feed(feed_url) - Quick subscribe with auto-discovery
• export_freshrss_subscriptions() - Export OPML
• import_freshrss_subscriptions(opml_content) - Import OPML
• edit_feed_subscription(feed_id, ...) - Edit feed properties

Content

• get_reading_list(count?, since_timestamp?, continuation?) - Get unread articles
• get_starred_articles(count?, ...) - Get starred items
• get_feed_articles(feed_id, count?, ...) - Get specific feed articles
• get_category_articles(category_name, count?, ...) - Get category articles

Item Operations

• mark_articles_as_read(item_ids) - Mark as read
• mark_articles_as_unread(item_ids) - Mark as unread
• star_articles(item_ids) - Star articles
• unstar_articles(item_ids) - Unstar articles
• add_label_to_articles(item_ids, label) - Add label
• remove_label_from_articles(item_ids, label) - Remove label
• mark_all_as_read_in_stream(stream_id, timestamp?) - Mark all as read

Categories

• list_categories() - List all categories
• get_unread_counts() - Get unread counts for all feeds
• rename_category(old_name, new_name) - Rename category
• delete_category(category_name) - Delete category

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test suite
pytest tests/unit/
pytest tests/integration/

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/

Architecture

The server uses a layered architecture:

• MCP Tools Layer: FastMCP tool definitions (26 tools)
• Service Layer: Manager classes for each API domain (Auth, Subscription, Stream, Item, Tag)
• HTTP Client Layer: GReader API client with retry logic and exponential backoff
• Storage Layer: SQLite for auth tokens and sync state

Security

• HTTPS-only connections to FreshRSS servers
• Auth tokens persisted in SQLite (consider SQLCipher for encryption)
• No plaintext password storage
• Input validation on all user inputs
• Parameterized SQL queries

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please ensure:

• Tests pass (pytest)
• Code is formatted (black src/)
• No linting errors (ruff check src/)
• Type checking passes (mypy src/)

Support

For issues, questions, or feature requests, please open an issue on GitHub.