https://github.com/aserper/masto-rss
A Mastodon bot that posts RSS updates to a Mastodon account
https://github.com/aserper/masto-rss
Last synced: 3 months ago
JSON representation
A Mastodon bot that posts RSS updates to a Mastodon account
- Host: GitHub
- URL: https://github.com/aserper/masto-rss
- Owner: aserper
- License: gpl-3.0
- Created: 2023-12-05T01:50:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-03T01:19:16.000Z (3 months ago)
- Last Synced: 2026-04-03T11:22:48.849Z (3 months ago)
- Language: Python
- Size: 361 KB
- Stars: 33
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Masto-RSS
[](https://github.com/aserper/masto-rss/actions/workflows/ci.yml)
[](https://hub.docker.com/r/amitserper/masto-rss)
[](https://github.com/aserper/masto-rss/pkgs/container/masto-rss)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/aserper/masto-rss)
[](https://github.com/aserper/masto-rss/network)
A simple, lightweight Mastodon bot that automatically posts updates from RSS feeds to the Fediverse. Built with Python and designed to run seamlessly in Docker with multiarch support (amd64 & arm64).
## Features
- Automatically monitors RSS/Atom feeds and posts new items to Mastodon
- Persistent state tracking to avoid duplicate posts
- Configurable post visibility (public, unlisted, private, direct)
- Lightweight Python Slim-based Docker image
- Multiarch support (amd64 & arm64) for broad compatibility
- Continuous monitoring with configurable check intervals
## Quick Start
### Using Docker (Recommended)
The easiest way to run Masto-RSS is using the pre-built multiarch Docker images available on both Docker Hub and GitHub Container Registry.
#### Pull from Docker Hub
```bash
docker pull amitserper/masto-rss:latest
```
#### Pull from GitHub Container Registry
```bash
docker pull ghcr.io/aserper/masto-rss:latest
```
#### Run the Bot
```bash
docker run -d \
--name masto-rss-bot \
-e MASTODON_CLIENT_ID="your_client_id" \
-e MASTODON_CLIENT_SECRET="your_client_secret" \
-e MASTODON_ACCESS_TOKEN="your_access_token" \
-e MASTODON_INSTANCE_URL="https://mastodon.social" \
-e RSS_FEED_URL="https://example.com/feed.xml" \
-e TOOT_VISIBILITY="public" \
-e CHECK_INTERVAL="300" \
-v /path/to/state:/state \
amitserper/masto-rss:latest
```
> **Important:** Use a bind mount for `/state` to persist the list of processed feed items across container restarts.
### Using Docker Compose
Create a `docker-compose.yml`:
```yaml
version: '3.8'
services:
masto-rss:
image: amitserper/masto-rss:latest
# Or use GHCR: ghcr.io/aserper/masto-rss:latest
container_name: masto-rss-bot
restart: unless-stopped
environment:
MASTODON_CLIENT_ID: "your_client_id"
MASTODON_CLIENT_SECRET: "your_client_secret"
MASTODON_ACCESS_TOKEN: "your_access_token"
MASTODON_INSTANCE_URL: "https://mastodon.social"
RSS_FEED_URL: "https://example.com/feed.xml"
TOOT_VISIBILITY: "public"
CHECK_INTERVAL: "300"
volumes:
- ./state:/state
```
Then run:
```bash
docker-compose up -d
```
### Multiple Feeds
To monitor multiple feeds, you can either:
- Use the `RSS_FEEDS` environment variable (comma-separated list)
- Use the `FEEDS_FILE` environment variable (path to file with one URL per line)
#### Run with Multiple Feeds (Docker)
```bash
docker run -d \
--name masto-rss-bot \
-e MASTODON_CLIENT_ID="your_client_id" \
-e MASTODON_CLIENT_SECRET="your_client_secret" \
-e MASTODON_ACCESS_TOKEN="your_access_token" \
-e MASTODON_INSTANCE_URL="https://mastodon.social" \
-e RSS_FEEDS="https://feed1.com/rss,https://feed2.com/rss" \
-e TOOT_VISIBILITY="public" \
-e CHECK_INTERVAL="300" \
-v /path/to/state:/state \
amitserper/masto-rss:latest
```
## Configuration
All configuration is done via environment variables:
| Variable | Description | Required | Example |
|----------|-------------|----------|---------|
| `MASTODON_CLIENT_ID` | Mastodon application client ID | Yes | `abc123...` |
| `MASTODON_CLIENT_SECRET` | Mastodon application client secret | Yes | `xyz789...` |
| `MASTODON_ACCESS_TOKEN` | Mastodon access token | Yes | `token123...` |
| `MASTODON_INSTANCE_URL` | URL of your Mastodon instance | Yes | `https://mastodon.social` |
| `RSS_FEED_URL` | Single RSS/Atom feed URL (Legacy) | No* | `https://example.com/feed.xml` |
| `RSS_FEEDS` | Comma-separated list of feed URLs | No* | `https://site1.com,https://site2.com` |
| `FEEDS_FILE` | Path to file containing list of feed URLs | No* | `/config/feeds.txt` |
| `TOOT_VISIBILITY` | Post visibility level | Yes | `public`, `unlisted`, `private`, or `direct` |
| `CHECK_INTERVAL` | Seconds between feed checks | Yes | `300` (5 minutes) |
| `ENABLE_REPLIES` | Enable sarcastic replies to mentions | No | `true` or `false` (default: false) |
| `PROCESSED_ENTRIES_FILE`| Custom path for state file | No | `/state/processed.txt` |
\* At least one of `RSS_FEED_URL`, `RSS_FEEDS`, or `FEEDS_FILE` must be provided.
### Getting Mastodon API Credentials
1. Log into your Mastodon instance
2. Go to **Settings** → **Development** → **New Application**
3. Give it a name (e.g., "RSS Bot")
4. Set scopes to `write:statuses`
5. Save and copy the client ID, client secret, and access token
## Building from Source
### Build Locally
```bash
git clone https://github.com/aserper/masto-rss.git
cd masto-rss
docker build -t masto-rss .
```
### Build Multiarch Images
```bash
# Set up buildx
docker buildx create --use
# Build for both architectures
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t yourusername/masto-rss:latest \
--push \
.
```
## Running Without Docker
If you prefer to run the bot directly with Python:
```bash
# Clone the repository
git clone https://github.com/aserper/masto-rss.git
cd masto-rss
# Install dependencies
pip install -r requirements.txt
# Set environment variables
export MASTODON_CLIENT_ID="your_client_id"
export MASTODON_CLIENT_SECRET="your_client_secret"
export MASTODON_ACCESS_TOKEN="your_access_token"
export MASTODON_INSTANCE_URL="https://mastodon.social"
export RSS_FEED_URL="https://example.com/feed.xml"
export TOOT_VISIBILITY="public"
export CHECK_INTERVAL="300"
# Run the bot
python main.py
```
> **Note:** When running without Docker, the bot stores its state in `/state/processed_entries.txt`. Make sure this directory exists or modify [main.py](main.py#L15) to use a different path.
## How It Works
1. The bot fetches the RSS feed at regular intervals (defined by `CHECK_INTERVAL`)
2. For each feed item, it checks if the item's URL has been processed before
3. If the item is new, it posts to Mastodon with the format: `{title}\n\n{link}`
4. The item URL is saved to prevent duplicate posts
5. The process repeats indefinitely
## Architecture
- **Base Image:** Python 3.12-slim (stable & compatible)
- **Python Version:** 3.10+
- **Platforms:** linux/amd64, linux/arm64
- **Dependencies:** feedparser, mastodon.py (see [requirements.txt](requirements.txt))
## State Persistence
The bot maintains state in `/state/processed_entries.txt` to track which feed items have already been posted. This prevents duplicate posts across restarts.
**Important:** Always mount `/state` as a volume to preserve this state file.
## Contributing
Contributions are welcome! Feel free to:
- Report bugs by opening an issue
- Submit pull requests for improvements
- Suggest new features or enhancements
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
## Support
If you find this project useful, please consider giving it a star on GitHub!
## Links
- [Docker Hub Repository](https://hub.docker.com/r/amitserper/masto-rss)
- [GitHub Container Registry](https://github.com/aserper/masto-rss/pkgs/container/masto-rss)
- [Source Code](https://github.com/aserper/masto-rss)
- [Issues](https://github.com/aserper/masto-rss/issues)