- name
- mastodon-scout
- description
- Read-only Mastodon skill. Outputs human-readable timeline summaries or raw JSON.
- metadata
- {"clawdhub":{"emoji":"🦣"},"clawdis":{"envVars":[{"name":"MASTODON_TOKEN","required":true},{"name":"MASTODON_INSTANCE","required":false,"default":"https://mastodon.social"}]}}
Mastodon Scout
Purpose
Read-only Mastodon skill. Fetches data from the Mastodon API via a bundled Python script (scripts/mastodon_scout.py). Returns human-readable summaries by default, or raw JSON with --json.
Invocation Rules (MANDATORY)
python3 ./scripts/mastodon_scout.py <command> [options]Commands
| Command | What it fetches |
|---|---|
home | Authenticated user's home timeline |
user-tweets | Authenticated user's own posts |
mentions | Mentions of the authenticated user |
search <query> | Posts matching the query |
Options
--instance <url> Mastodon instance base URL (default: $MASTODON_INSTANCE or https://mastodon.social)
--limit <int> Number of items to return (default: $LIMIT or 20)
--json Output raw JSON instead of human-readable textEnvironment Variables
MASTODON_TOKEN Required. OAuth bearer token.
MASTODON_INSTANCE Optional. Instance base URL (default: https://mastodon.social).Examples
python3 ./scripts/mastodon_scout.py home
python3 ./scripts/mastodon_scout.py mentions --limit 10
python3 ./scripts/mastodon_scout.py search "golang"
python3 ./scripts/mastodon_scout.py home --json
python3 ./scripts/mastodon_scout.py home --instance https://fosstodon.orgOutput Modes
Text Mode (Default)
The script formats each post as:
[N] Display Name (@user@instance) · <timestamp>
<content>
↩ <replies> 🔁 <reblogs> ⭐ <favourites>
<url>The agent MAY add a brief summary after the list.
JSON Mode (--json)
Returns raw Mastodon API JSON. Return it verbatim — no interpretation.
Error Handling
The script prints a human-readable error to stderr and exits non-zero:
| Condition | Message |
|---|---|
| Token missing | Error: MASTODON_TOKEN is not set |
| 401 | Mastodon API error: 401 Unauthorized — check MASTODON_TOKEN |
| 403 | Mastodon API error: 403 Forbidden |
| 422 | Mastodon API error: 422 Unprocessable Entity |
| 429 | Mastodon API error: 429 Rate Limited — try again later |
Do not retry on error. Guide the user to Authentication Setup if the token is missing or invalid.
Examples That Trigger This Skill
mastodon-scout homeshow my mastodon timelinecheck mastodon mentionssearch mastodon for "golang"get my mastodon posts
Notes
- This skill is read-only (no posting, following, or other mutations)
scripts/mastodon_scout.pyuses stdlib only — no pip install required- In JSON mode: output verbatim, no interpretation
Authentication Setup (Agent MAY Help)
EXCEPTION TO STRICT MODE: If the user needs help obtaining a token, the agent may provide guidance before executing the skill.
How to Obtain a Token:
Step 1: Access Development Settings
- Log into your Mastodon instance (e.g., mastodon.social, fosstodon.org)
- Navigate to: Settings → Development (or Preferences → Development)
- Direct URL:
https://[instance-domain]/settings/applications
Step 2: Create Application
- Click "New Application"
- Application name: mastodon-scout (or any name) - Redirect URI: urn:ietf:wg:oauth:2.0:oob - Scopes: CRITICAL — only select read (uncheck write, follow, push)
Step 3: Get Access Token
- Click Submit, then open the created application
- Copy the "Your access token" value
Step 4: Set Environment Variable
export MASTODON_TOKEN="paste_token_here"Step 5: Verify
python3 ./scripts/mastodon_scout.py home --limit 5Common Mastodon Instances:
mastodon.social— General purpose (default)fosstodon.org— FOSS/tech communitymas.to— Tech focusedhachyderm.io— Tech/infosec community
Security Notes:
- Token is read-only (cannot post, follow, or delete)
- Keep token secret (don't commit to git)
- Can be revoked anytime in Development settings
- Each Mastodon instance requires its own token