FeedFlow MCP Server

---

FeedFlow is a stdio-based FastMCP server designed for managing and fetching articles from RSS feeds. It allows you to add, list, and read from multiple RSS feed sources directly through MCP tool calls, using a persistent SQLite database.

---

Features

• Add & Manage RSS Feeds: Persistently add new RSS feeds to the database.
• Categorize Feeds: Assign a category and language to each feed for better organization.
• List Feeds: Retrieve a list of all stored feeds, or filter them by category.
• Fetch Articles: Get the latest articles from any given RSS feed URL, with summaries.
• SQLite: All feed data is stored in a local SQLite database (windows: %LOCALAPPDATA%).
• Language Detection: Automatically detects the language of a feed's content if not specified.
• Asynchronous: Built with asyncio, aiosqlite, and httpx for non-blocking I/O.

Prerequisites

• Python 3.13+
• uv (for installing dependencies from uv.lock)

📦 Installation & 📋 Usage

FeedFlow is designed to run as an MCP server. You don't need to install it manually; uv handles everything.

🛠️ Developer Setup

1. Clone the repository:

   git clone https://github.com/geckod22/FeedFlow
   cd FeedFlow

2. Install in editable mode: This project uses uv. To set up a virtual environment and install all dependencies (including test tools):

   uv sync
   uv pip install -e .

⚙️ MCP Client configuration

🚀 Quick Start (without cloning the repository)

you can run FeedFlow directly from PyPi

"feedflow": {
  "command": "uvx",
  "args": ["feedflow"]
}

or if you use Gemini CLI or other terminal-based clients, you can run it from github:

"feedflow": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/geckod22/FeedFlow", "feedflow"]
}

🔧 Standard config\DEV:

if you cloned the repo on your machine

    "feedflow": {
		"command": "uv",
		"args": [
        "--directory", "full_path_to_FeedFlow_main_folder",
        "run", "feedflow"
    	]
    }

Client	DOC
Claude Desktop	here
Copilolt / VS Code	here
Cursor	Go to Cursor Settings -> MCP -> New MCP Server. Use the General config above.
Gemini CLI	here
Windsurf	here

🛠️ Available Tools & Resources

📦 Resources

• feeds://feeds: Returns a list of all configured RSS feeds.
• feeds://categories: Returns a list of all unique feed categories.
• feeds://feeds/{category}: Returns a list of RSS feeds filtered by a specific category.

💬 Prompts

• available_feeds_categories: Returns a list of all unique feed categories.

🔧 Tools

add_feed

Adds a new RSS feed to the database.

• Parameters:
  • url (str, required): The URL of the RSS feed.
  • name (str, required): A descriptive name for the feed.
  • category (str, optional): The category for the feed (default: General).
  • lang (str, optional): The 2-letter ISO code for the language (default: en).

remove_feed

Removes a feed from the database.

• Parameters:
  • feed (str, required): The URL or the title/name of the feed to remove.

list_feeds

Returns the list of saved RSS feeds.

• Parameters:
  • category (str, optional): If provided, filters the feeds by this category.

fetch_rss_feed

Fetches and displays the latest articles from a given RSS feed URL.

• Parameters:
  • url (str, required): The URL of the RSS feed to fetch.
  • max_results (int, optional): The maximum number of articles to return (default: 5, max: 10).

🔍 Test with modelcontextprotocol/inspector

from the project folder run:

npx @modelcontextprotocol/inspector uv run feedflow

🧪 Running Tests

To run the test suite, use pytest:

uv run pytest

with coverage

uv run pytest --cov=feedflow --cov-report=html

for coverage badge

uv run pytest --cov=feedflow --local-badge-output-dir .

📄 License

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

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the project.