MMM-Mastodon is a MagicMirror² module that brings the decentralized world of Mastodon to your smart mirror. Display your home timeline, follow hashtags, or track profiles with customizable options for media, rotation, and more – all while staying connected to the fediverse.
- Fetch posts from Mastodon's home timeline, hashtag streams, or profile feeds.
- Configurable refresh interval, maximum items, media display, and more.
- Graceful handling of rate limits and API failures.
cd ~/MagicMirror/modules
git clone https://github.com/KristjanESPERANTO/MMM-Mastodon
cd MMM-Mastodon
npm ci --omit=devGo to the module’s directory and pull the latest version from GitHub:
cd ~/MagicMirror/modules/MMM-Mastodon
git pull
npm ci --omit=devAdd the module to the modules array in your config/config.js:
{
module: "MMM-Mastodon",
position: "top_left",
config: {
instanceUrl: "https://mastodon.social",
accessToken: "YOUR_ACCESS_TOKEN",
feedType: "profile", // home | hashtag | profile
hashtag: "news", // required when feedType === "hashtag"
profileAcct: "@ScienceNews@mstdn.social", // required when feedType === "profile"
limit: 10,
updateInterval: 300000,
showMedia: true,
dateFormat: "relative", // relative | absolute
hideReplies: true,
showQrCode: true,
qrCodeSize: 128,
maxLinkLength: 80,
rotatePosts: true,
rotationInterval: 15000
}
},| Option | Type | Default | Description |
|---|---|---|---|
instanceUrl |
string |
– | Base URL of your Mastodon instance. |
accessToken |
string |
– | Mastodon access token with read scope. |
feedType |
string |
home |
Which timeline endpoint to read (home, hashtag, or profile). |
hashtag |
string |
– | Required for hashtag feeds; do not include #. |
profileAcct |
string |
– | Mastodon handle such as user@example.com; required for profile feeds. |
limit |
number |
10 |
Maximum number of statuses to display. |
updateInterval |
number |
300000 |
Refresh rate in milliseconds. |
showMedia |
boolean |
true |
Whether to show attached images/videos as thumbnails. |
dateFormat |
string |
relative |
Display timestamps relatively or as formatted dates. |
hideReplies |
boolean |
true |
Exclude reply posts; helpful for profile feeds focused on top-level posts. |
showQrCode |
boolean |
true |
Render a scannable QR code that links directly to each post. |
qrCodeSize |
number |
128 |
Width/height (px) of the generated QR code when enabled. |
maxLinkLength |
number | false |
30 |
Trim overly long link text. Use 0 to hide link text entirely, or false to leave links untouched. |
rotatePosts |
boolean |
true |
Show one post at a time and rotate through the latest items. |
rotationInterval |
number |
15000 |
Interval in milliseconds between rotations when rotatePosts is enabled. |
- Log into your Mastodon instance.
- Visit Settings → Development → New application.
- Give it a name (e.g.,
MagicMirror), enable read:statuses and read:accounts scopes. - Save and copy the generated Access Token into the module configuration.
- Additional Mastodon timeline filters (bookmarks, lists)
- Inline media playback controls
- Optional notifications panel
- Additional styling and localization
If you find any problems, bugs or have questions, please open a GitHub issue in this repository.
Pull requests are of course also very welcome 🙂
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
npm install- Install development dependencies.node --run lint- Run linting and formatter checks.node --run lint:fix- Fix linting and formatter issues.node --run test- Run linting and formatter checks + run spelling check.node --run test:spelling- Run spelling check.
This project is licensed under the MIT License - see the LICENSE file for details.
All notable changes to this project will be documented in the CHANGELOG.md file.
