A read-only utility for fetching Mastodon timelines, mentions, and search results via a dependency-free Python script.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install mastodon-scout
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install mastodon-scout using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Mastodon Scout?
Mastodon Scout is a specialized tool designed to bridge the gap between AI agents and the decentralized social web. It provides a lightweight, read-only interface to fetch home timelines, user posts, and mentions from any Mastodon instance. By utilizing Openclaw Skills, developers can integrate real-time social data into their automated workflows without the overhead of heavy dependencies, as the skill relies solely on Python's standard library.
This skill prioritizes security and simplicity. It operates using an OAuth bearer token with restricted read-only permissions, ensuring that your account remains secure while providing the agent with the necessary context from your social graph. Whether you are monitoring tech trends or keeping up with personal mentions, this skill provides a clean, parseable way to interact with Mastodon data.
Mastodon Scout Use Cases
- Fetching the latest posts from your Mastodon home timeline for a morning briefing.
- Searching for specific keywords or hashtags like "golang" or "AI" across the Mastodon network.
- Monitoring account mentions to stay updated on community interactions without opening a browser.
- Exporting social data in raw JSON format for further programmatic analysis or data archival.
How Mastodon Scout Works
- The agent or user triggers the script using a specific command like home, mentions, or search.
- The script authenticates with the designated Mastodon instance using a secure OAuth token stored in environment variables.
- A GET request is sent to the Mastodon API to retrieve the requested data subset.
- The script processes the raw API response and applies formatting logic.
- The final output is returned to the user in a human-readable list format or as a raw JSON object for further processing within the Openclaw Skills framework.
Mastodon Scout Setup
To integrate this with Openclaw Skills, follow these installation and configuration steps:
- Generate a token by navigating to Settings -> Development on your Mastodon instance. Create a new application and ensure only the read scope is selected.
- Set your environment variables in your terminal or configuration file:
export MASTODON_TOKEN="your_access_token"
export MASTODON_INSTANCE="https://mastodon.social"
- Verify the installation by running a simple command:
python3 ./scripts/mastodon_scout.py home --limit 5
Mastodon Scout Data Schema & Taxonomy
The skill organizes its output into two primary modes to accommodate both human users and automated agents.
Text Mode Organization
| Field | Description |
|---|---|
| Header | Display name, handle, and timestamp |
| Content | The text body of the Mastodon post |
| Interaction | Counts for replies, reblogs, and favorites |
| Metadata | Direct URL to the original post |
JSON Mode
When the --json flag is used, the skill returns the raw Status entity from the Mastodon API, preserving all original metadata and taxonomy for deep analysis.
Mastodon Scout Advanced Features
- Multi-Instance Support: Switch between different instances like fosstodon.org or hachyderm.io using the --instance flag.
- Raw Data Passthrough: Use the --json option to feed raw data directly into other Openclaw Skills for complex data pipelines.
- Adjustable Fetch Limits: Control the volume of data retrieved per request using the --limit parameter.
- Zero-Dependency Architecture: Built entirely on the Python standard library, ensuring compatibility across diverse environments without needing pip install.
SKILL.md
Loading
Related Openclaw Skills
Market Monitor
A real-time market analysis tool for monitoring crypto price trends and technical indicators across major exchanges.
System Resource Monitor
A lightweight and reliable utility for monitoring CPU load, memory usage, and disk health directly through your AI agent.
whcli: Willhaben Classifieds CLI
A command-line interface for searching and browsing willhaben.at, Austria's largest classifieds marketplace.
virus-monitor
A command-line tool for aggregating Austrian wastewater and sentinel surveillance data for real-time virus monitoring.
Weather NWS Skill
A high-precision weather forecasting skill for AI agents providing NWS data, winter storm tracking, and air quality metrics with global fallback support.
Skill Flag Security Scanner
A specialized security auditing tool designed to scan AI coding agent skills for malicious patterns, backdoors, and credential theft risks.
METADATA
Featured*
