mastodon-admin

Automate Mastodon instance moderation, signup approval, and welcome DMs via the admin API.

10|2|Updated May 6, 2026
One-click install
npx skills add https://github.com/jcrabapple/hermes-skills --skill mastodon-admin-jcrabapple
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mastodon-admin
Source: https://github.com/jcrabapple/hermes-skills/tree/main/mastodon-admin
Command: npx skills add https://github.com/jcrabapple/hermes-skills --skill mastodon-admin-jcrabapple

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Running a Mastodon instance means constantly triaging moderation reports, screening signup requests for spam, and onboarding new members — repetitive admin work that piles up fast. This Skill automates that triage using the Mastodon admin API with a documented decision framework. ## Core Features & Use Cases - Report Moderation: Fetch unresolved reports, classify them against instance rules, auto-suspend or silence clear violations (spam, hate speech, illegal content), and escalate ambiguous cases to the instance owner. - Signup Approval Assistant: Screen pending registrations against DMV-area location signals, an 8,200+ disposable email domain blocklist, and Tor exit node screening, then auto-approve, reject, or escalate. - Welcome Bot: Send a personalized direct-message welcome to newly approved local accounts, with a state file preventing duplicate DMs and an age filter preventing belated welcomes. - Use Case: An hourly cron job runs the report monitor, which suspends a spam bot, dismisses an empty report, and escalates a borderline AI-art case to you with the report details and admin link. ## Quick Start Ask the agent to check Mastodon reports and handle any clear violations on the instance.

Frequently Asked Questions about mastodon-admin

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate Mastodon moderation reports?▼

Use the admin API endpoint /api/v1/admin/reports to fetch unresolved reports, classify them against instance rules, then call the account action endpoint to suspend or silence violators and resolve the report. The included mastodon_reports.py script automates this full loop.

How to screen Mastodon signups for spam accounts?▼

Fetch pending accounts with /api/v1/admin/accounts?pending=true, then check invite request text for location signals, match email domains against a disposable domain blocklist, and screen registration IPs against the Tor exit list. Approve, reject, or escalate based on the combined signals.

Why does the Mastodon admin API return 403 on all endpoints?▼

A 403 with 'outside the authorized scopes' means the OAuth token was created without admin scopes, even if the user is the instance Owner. Register a new OAuth app with admin:read and admin:write scopes and re-authorize to get a working token.

Why does status=pending not filter Mastodon admin accounts?▼

The v1 admin API silently drops the status parameter because it is not in the permitted filter list, returning every active local account instead. Use the legacy boolean pending=true on v1, or switch to the v2 API which accepts status=pending directly.

Can I send welcome DMs to new Mastodon users automatically?▼

Yes, post a status with visibility=direct and an @mention of the new user so they receive a notification. Track welcomed account IDs in a state file and skip accounts older than seven days to avoid belated welcomes.

When should I silence instead of suspend a Mastodon account?▼

Silence first offenses of hate speech or harassment, since silencing only hides posts from public timelines. Reserve suspension for severe or repeat violations, spam, and illegal content, because suspension deletes posts and is only reversible within about 30 days.