{"id":31779534,"url":"https://github.com/xz-dev/rss-mcp","last_synced_at":"2025-10-10T07:51:05.079Z","repository":{"id":315916039,"uuid":"1061022270","full_name":"xz-dev/rss-mcp","owner":"xz-dev","description":"RSS MCP Tool for AI","archived":false,"fork":false,"pushed_at":"2025-09-21T16:04:11.000Z","size":215,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-21T16:31:26.482Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xz-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-21T04:36:09.000Z","updated_at":"2025-09-21T16:04:14.000Z","dependencies_parsed_at":"2025-09-21T16:31:28.039Z","dependency_job_id":"3463a9f4-5c3c-4a74-b7fd-b75cfb773682","html_url":"https://github.com/xz-dev/rss-mcp","commit_stats":null,"previous_names":["xz-dev/rss-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/xz-dev/rss-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xz-dev%2Frss-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xz-dev%2Frss-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xz-dev%2Frss-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xz-dev%2Frss-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xz-dev","download_url":"https://codeload.github.com/xz-dev/rss-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xz-dev%2Frss-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003173,"owners_count":26083533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T07:51:03.759Z","updated_at":"2025-10-10T07:51:05.071Z","avatar_url":"https://github.com/xz-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📰 RSS MCP Server\n\n\u003e 🚀 A powerful RSS feed management system with Model Context Protocol (MCP) integration, enabling AI assistants to intelligently analyze, aggregate, and track RSS content evolution.\n\n## ✨ Features\n\n- 🔄 **Multi-Source Feeds**: Multiple RSS sources per feed with automatic failover\n- 🤖 **MCP Integration**: Full Model Context Protocol support (stdio, HTTP, SSE)\n- 📊 **Content Evolution Tracking**: AI can analyze how news stories develop over time\n- ⚡ **Intelligent Caching**: Efficient content storage with deduplication\n- 🔍 **Time-based Filtering**: Query entries by publication date ranges\n- 👥 **Multi-user Support**: Isolated configurations and data per user\n- 🐳 **Docker Ready**: Containerized deployment support\n- 🛠️ **Rich CLI**: Comprehensive command-line interface\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# From PyPI\npip install rss-mcp\n\n# From source\ngit clone https://github.com/xz-dev/rss-mcp.git\ncd rss-mcp\nuv sync\n```\n\n### Basic Usage\n\n```bash\n# Add RSS feed\nrss-mcp feed add \"tech-news\" \"https://feeds.feedburner.com/TechCrunch\" \\\n  --title \"TechCrunch\" --description \"Latest tech news\"\n\n# Fetch entries\nrss-mcp fetch\n\n# View recent entries\nrss-mcp entries --since \"1 day ago\" --limit 10\n\n# Start MCP server\nrss-mcp serve stdio\n```\n\n## 🔌 MCP Configuration\n\n### stdio Mode (Recommended)\nFor Claude Desktop, Continue.dev, and other local MCP clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"rss-mcp\": {\n      \"command\": \"rss-mcp\",\n      \"args\": [\"serve\", \"stdio\"],\n      \"env\": {\n        \"RSS_MCP_USER\": \"your-username\"\n      }\n    }\n  }\n}\n```\n\n### HTTP Mode\nFor remote deployment and web-based clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"rss-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-server.com/mcp\",\n      \"headers\": {\n        \"X-User-ID\": \"your-username\"\n      }\n    }\n  }\n}\n```\n\n### SSE Mode (Deprecated)\nFor legacy Server-Sent Events transport:\n\n```json\n{\n  \"mcpServers\": {\n    \"rss-mcp\": {\n      \"type\": \"sse\",\n      \"url\": \"https://your-server.com/sse\",\n      \"headers\": {\n        \"X-User-ID\": \"your-username\"\n      }\n    }\n  }\n}\n```\n\n## 🤖 MCP Tools\n\nThe server provides these tools for AI assistants:\n\n| Tool | Description | Usage |\n|------|-------------|-------|\n| `list_feeds` | List all configured RSS feeds | Get feed overview |\n| `get_entries` | Retrieve RSS entries with filtering | Analyze recent content |\n| `add_feed` | Create new RSS feed | Setup new sources |\n| `add_source` | Add backup URL to feed | Improve reliability |\n| `remove_feed` | Delete feed and entries | Clean up |\n| `remove_source` | Remove source URL | Maintenance |\n| `refresh_feeds` | Fetch latest entries | Update content |\n| `get_feed_stats` | Get feed statistics | Monitor activity |\n\n### Example AI Interactions\n\n```\nUser: \"Show me tech news from the last 6 hours\"\nAI: Uses get_entries with since parameter to fetch recent entries\n\nUser: \"Track how this breaking news story has evolved\"\nAI: Uses get_entries to find multiple versions of the same story by GUID\n\nUser: \"Add a backup source for my news feed\"\nAI: Uses add_source to improve feed reliability\n```\n\n## 🛠️ CLI Reference\n\n### Feed Management\n```bash\n# Feed operations\nrss-mcp feed add \u003cname\u003e \u003curl\u003e [--title TITLE] [--description DESC]\nrss-mcp feed list [--active-only] [--verbose]\nrss-mcp feed remove \u003cname\u003e\nrss-mcp feed enable/disable \u003cname\u003e\n\n# Source operations  \nrss-mcp source add \u003cfeed_name\u003e \u003curl\u003e [--priority N]\nrss-mcp source remove \u003cfeed_name\u003e \u003curl\u003e\n\n# Content operations\nrss-mcp fetch [--feed FEED] [--force]\nrss-mcp entries [--feed FEED] [--since TIME] [--limit N]\nrss-mcp stats [--feed FEED]\n```\n\n### Server Modes\n```bash\n# stdio mode (for local MCP clients)\nrss-mcp serve stdio\n\n# HTTP mode (for remote access)\nrss-mcp serve http --host 0.0.0.0 --port 8080\n\n# SSE mode (deprecated)\nrss-mcp serve sse --host 0.0.0.0 --port 8080\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `RSS_MCP_CONFIG_DIR` | Configuration directory | `~/.config/rss-mcp` |\n| `RSS_MCP_CACHE_DIR` | Cache directory | `~/.cache/rss-mcp` |\n| `RSS_MCP_USER` | Default user ID | `default` |\n| `RSS_MCP_REQUIRE_USER_ID` | Require user ID for access | `false` |\n\n### Multi-user Setup\n\nFor multi-tenant deployments:\n\n```bash\n# Enable user ID requirement\nexport RSS_MCP_REQUIRE_USER_ID=1\n\n# Start server (users must provide X-User-ID header)\nrss-mcp serve http --host 0.0.0.0 --port 8080\n```\n\n## 🐳 Docker Deployment\n\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install .\n\n# Set environment variables\nENV RSS_MCP_CONFIG_DIR=/app/config\nENV RSS_MCP_CACHE_DIR=/app/cache\nENV RSS_MCP_REQUIRE_USER_ID=1\n\nEXPOSE 8080\nCMD [\"rss-mcp\", \"serve\", \"http\", \"--host\", \"0.0.0.0\", \"--port\", \"8080\"]\n```\n\n```bash\n# Build and run\ndocker build -t rss-mcp .\ndocker run -p 8080:8080 -v ./config:/app/config -v ./cache:/app/cache rss-mcp\n```\n\n## 🎯 Use Cases\n\n### News Analysis\n- **Story Evolution**: Track how breaking news develops over time\n- **Source Comparison**: Compare reporting across different outlets\n- **Trend Detection**: Identify emerging topics and patterns\n\n### Content Aggregation\n- **Multi-source Feeds**: Combine multiple RSS sources for comprehensive coverage\n- **Intelligent Deduplication**: Avoid duplicate content across sources\n- **Reliability**: Automatic failover when sources are unavailable\n\n### AI Integration\n- **Content Summarization**: Let AI analyze and summarize RSS content\n- **Semantic Search**: Find relevant articles based on meaning, not just keywords\n- **Automated Insights**: Generate reports on content trends and patterns\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   MCP Client    │    │   RSS Sources   │    │  Configuration  │\n│  (Claude, etc.) │    │  (Web Feeds)    │    │     Files       │\n└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘\n          │                      │                      │\n          │ MCP Protocol         │ HTTP Fetch           │ JSON\n          │                      │                      │\n          ▼                      ▼                      ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                    RSS MCP Server                               │\n├─────────────────┬─────────────────┬─────────────────────────────┤\n│  FastMCP Core   │  Feed Manager   │      Cache Storage          │\n│  (Tools/Proto)  │  (RSS Parsing)  │   (Entries/Deduplication)   │\n└─────────────────┴─────────────────┴─────────────────────────────┘\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/xz-dev/rss-mcp.git\ncd rss-mcp\nuv sync --dev\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run black src tests\nuv run isort src tests\n```\n\n## 📝 License\n\nThis project is licensed under the BSD 2-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Credits\n\n- Built with [FastMCP](https://github.com/stpmax/fastmcp) for MCP protocol support\n- Uses [feedparser](https://feedparser.readthedocs.io/) for RSS parsing\n- Powered by [FastAPI](https://fastapi.tiangolo.com/) for HTTP transport\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003cstrong\u003eMade with ❤️ for the AI community\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eEnabling AI assistants to understand and analyze the world's RSS feeds\u003c/sub\u003e\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxz-dev%2Frss-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxz-dev%2Frss-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxz-dev%2Frss-mcp/lists"}