# Mastodon MCP > Mastodon connects your AI agent directly to the Fediverse, letting you post statuses, manage follows, and track trends across decentralized social media. You can handle everything from drafting a toot with `post_status` to analyzing trending topics using tools like `get_trending_tags`, all without leaving your workflow. ## Overview - **Category:** communication-messaging - **Price:** Free - **Tags:** fediverse, microblogging, activitypub, social-automation, mastodon-api ## Description Mastodon connects your agent directly to the Fediverse. You can manage every damn thing on your social profile—from posting out a quick toot to tracking down what's hot right now—all through your AI client. **Posting and Content Control.** Use `post_status` to publish new content instantly, specifying exactly who sees it. If you wanna share someone else’s post or 'boost' it, hit up `reblog_status`. You can also mark statuses you like using `favourite_status`, or if you gotta clean house and delete a post immediately, call `delete_status`. When you write content that includes media—an image or video—you first run `upload_media` to get it uploaded asynchronously; then you use `get_media` to check its upload status, and finally, you can fine-tune the descriptive text using `update_media`. **Managing Your Network.** You control who you talk to. To start following a user, run `follow_account`. If you need distance from someone but don't wanna officially unfollow them, use `mute_account`. You can instantly cut off all interaction with an account by running `block_account`. Need to drop yourself from someone else’s feed? Use `unfollow_account`. To keep tabs on specific people, run `get_account` to pull general profile info or `get_account_statuses` to see a list of their past posts. For deep dives into threads, `get_status_context` maps out all related statuses, showing both ancestors and descendants. **Sifting Through the Noise.** You don't wanna scroll forever just to find something good. Use `get_home_timeline` for everything you follow. If you want a view of every public post on the entire server—like looking at the main town square—use `get_public_timeline`. To filter stuff by topic, run `get_tag_timeline` using a specific hashtag. Want to know what people are really talking about right now? You check two things: `get_trending_statuses` gives you a list of the most popular posts, and `get_trending_tags` lists all the hot topics being discussed. **Discovering Content.** The general-purpose `search` tool lets you perform broad searches across accounts, statuses, or hashtags on the server. You can also view curated content feeds by running `get_list_timeline` against a specific list you created. For single items, `get_status` retrieves all the full content and metadata for one post, while if you’re just checking out what an account posted, use `get_account_statuses`. **Taming Your Notifications & Profile.** You gotta keep your settings current. Run `update_credentials` to change core profile info like your bio or display name. To deal with the notification pile-up, you can run `clear_notifications` to reset everything, or use `dismiss_notification` to mark single alerts as handled. For the latest API standards (Mastodon 4.3+), `get_notifications_v2` pulls grouped and categorized notifications; if that fails, you've got `get_notifications_v1`. **System Tools & Utility.** You can always verify your setup by running `verify_credentials` to ensure your account info is legit, or using `check_health` to confirm the server itself is up and running. Need to know what rules you gotta live by? `get_instance_rules` shows them, and `get_instance_info` gives general details about this specific server instance. You can even register a whole new account with `register_account`, or if you're building an app for the platform, `create_app` handles that setup. That’s it—you get direct access to every part of your decentralized social presence. Your agent treats Mastodon like a straightforward API endpoint. ## Tools ### clear_notifications Resets all notifications displayed in your account dashboard. ### unfollow_account Removes yourself from following another user's account. ### block_account Blocks a specific Mastodon account from interacting with your profile. ### bookmark_status Saves the current status so you can find it again later on your profile. ### check_health Verifies if the Mastodon server is online and operational. ### create_app Generates a new Mastodon application for development purposes. ### delete_status Removes an existing status post from your profile immediately. ### dismiss_notification Marks a single notification as read or dealt with. ### favourite_status Adds a favorite marker to an existing status you appreciate. ### follow_account Starts following another user's account on the instance. ### get_account_statuses Fetches a list of status updates previously posted by a specific user. ### get_account Retrieves general profile information for any specified Mastodon account. ### get_home_timeline Shows statuses from all the accounts you are currently following. ### get_instance_info Retrieves general details about the specific Mastodon server instance. ### get_instance_rules Displays the community rules and guidelines for this specific server. ### get_list_timeline Views status updates contained within a predefined list you created. ### get_notifications_v1 Views a list of notifications for your user profile using the older API version. ### get_notifications_v2 Retrieves grouped and categorized notifications for your account using the latest API standard (Mastodon 4.3+). ### get_public_timeline View all public statuses posted anywhere on the server, regardless of who you follow. ### get_status_context Maps out all related statuses in a thread, showing both ancestors and descendants. ### get_status Retrieves the full content and metadata for a single status post. ### get_tag_timeline Displays a feed composed only of statuses that include a specific hashtag. ### get_trending_links Shows which external websites or links are currently gaining traction on the instance. ### get_trending_statuses Retrieves a list of the most popular status posts right now. ### get_trending_tags Lists and retrieves the hashtags that are currently trending or being discussed heavily. ### mute_account Silences all posts from a specific account without unfollowing them. ### post_status Publishes a brand new status update (toot) to your profile with specified visibility. ### reblog_status Shares or 'boosts' an existing status from another user onto your own timeline. ### register_account Handles the process of creating a brand new Mastodon account. ### search Performs a broad search across accounts, statuses, and hashtags on the server. ### update_credentials Modifies your core profile metadata, like your bio or display name. ### verify_credentials Checks that your current account credentials are valid and up-to-date. ## Prompt Examples **Prompt:** ``` Post a new status saying 'Hello from my AI agent!' with public visibility. ``` **Response:** ``` I've posted your status using `post_status`. It is now live on your profile with public visibility. ``` **Prompt:** ``` Show me the top 5 trending tags on this instance. ``` **Response:** ``` Fetching trends... The top tags currently are #Technology, #Art, #Fediverse, #News, and #Photography. ``` **Prompt:** ``` Verify my account and show my profile details. ``` **Response:** ``` Credentials verified! Your account is '@user@instance.social', with 150 followers and 200 following. Your bio is currently set to 'AI Enthusiast'. ``` ## Capabilities ### Create and edit statuses Write new posts (toots), reply to existing threads, or delete content using tools like `post_status` and `delete_status`. ### Manage connections and feeds Follow, unfollow, mute accounts (`follow_account`, `unfollow_account`), or get detailed account profiles via `get_account`. ### Track real-time activity View your personalized timeline using `get_home_timeline`, or see what’s currently popular with tools like `get_trending_tags` and `get_trending_statuses`. ### Control notifications and settings Clear notification lists (`clear_notifications`), dismiss single alerts, or even update your profile details using `dismiss_notification` and `update_credentials`. ### Search and discover content Find specific accounts, statuses, or hashtags across the instance using the general `search` tool. ## Use Cases ### Monitoring a breaking news event A journalist needs real-time data. They ask their agent to fetch all status updates related to 'Election2024' using `get_tag_timeline`. The agent returns a structured feed, allowing the journalist to analyze public sentiment without sifting through hundreds of posts. ### Curating weekly content digests A community manager wants to plan next week’s topics. They ask the agent to check `get_trending_statuses` and cross-reference that data with accounts they follow using `get_home_timeline`. This gives them material for a digest email. ### Cleaning up old account clutter A user wants to clean their profile. They ask the agent to run through all notifications (`get_notifications_v2`), dismiss everything using `dismiss_notification`, and then delete an old, embarrassing status with `delete_status`. ### Researching a competitor's activity A marketer wants to see what a rival is posting. They use the agent to run `get_account_statuses` for the rival account and analyze the last 50 posts to spot patterns in their content strategy. ## Benefits - You control your entire social presence. Use `post_status` to publish a toot with specific visibility settings (private, unlisted) without leaving your AI client. - Stop manually checking feeds. Query the top discussions instantly by using `get_trending_tags`, or see what’s happening everywhere on the public feed via `get_public_timeline`. - Handle account maintenance in bulk. Use `clear_notifications` and `dismiss_notification` to clear out your inbox, then use `update_credentials` when you need to change your bio. - Deep interaction capability. You can easily boost content using `reblog_status`, or save a status for later review by calling `bookmark_status` on the fly. - Comprehensive discovery. The `search` tool lets you find specific accounts, statuses, or hashtags across the entire instance, saving time compared to manual browsing. ## How It Works The bottom line is that your AI client runs Mastodon commands directly, giving you control over posts, follows, and timeline visibility without logging into a separate web browser. 1. First, subscribe to this server on Vinkius and provide your Mastodon Personal Access Token. 2. Next, you tell your AI client what action to take (e.g., 'Find the top 5 trending tags'). 3. Your agent calls the appropriate tool (`get_trending_tags`), retrieves the data, and presents the results back through natural conversation. ## Frequently Asked Questions **How do I post status updates using the post_status tool?** You call `post_status` and provide three things: the text content, the visibility setting (public, unlisted, private), and any media attachments. The agent then sends it live to your feed. **What is the difference between get_home_timeline and get_public_timeline?** `get_home_timeline` only shows posts from people you follow, keeping your view focused on your direct network. `get_public_timeline` pulls every public post across the entire server instance. **Can I see what accounts are trending with get_trending_tags?** Yes, `get_trending_tags` fetches a list of the most popular hashtags right now. You can then use these specific tags to narrow down your search using `get_tag_timeline`. **How do I delete an old status post?** You use the `delete_status` tool, providing the unique ID of the post you want gone. It removes it immediately from your profile. **What should I run first to make sure my account works?** Always call `verify_credentials`. This checks that your access token is still valid and that all your profile details are up-to-date before you attempt any reads or writes. **If I run `follow_account`, what information do I need to provide?** You simply pass the target account's handle and instance URL. The tool sends a follow request through the API and confirms if you successfully connected with that user. **After uploading content, how do I check its status using `get_media`?** The tool checks the asynchronous upload status of your media attachment. It returns a status code so you know when the file is fully processed and ready to be linked or posted. **Using `get_notifications_v2`, what kind of activity can I track?** This tool retrieves grouped notifications, detailing mentions, replies, and other user interactions. It lets you see a summary of your recent account activities in one place. **Can I post a status with a content warning (spoiler text)?** Yes. When using the `post_status` tool, you can provide a `spoiler_text` string which will act as a content warning for your followers. **How do I verify if my access token is working correctly?** You can use the `verify_credentials` tool. It will test your current token and return your authenticated profile information if successful. **Is it possible to see what is currently trending on my instance?** Absolutely. Use the `get_trending_tags` tool to retrieve the most popular hashtags used on your instance recently.