Mastodon MCP Server — 115 tools
The Mastodon DADL turns Mastodon's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 115 tools — status, account, filter, instance, featured, notification, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.
Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Mastodon feature area, required credential scopes.
Source: Mastodon REST API v1/v2
Which Mastodon endpoints are covered?
86% (112 of ~130 endpoints)
Focus: accounts (lookup + verify + follow/unfollow + mute/block + relationships + search), statuses (CRUD + favourite + reblog + bookmark + pin + context + translate), timelines (home + public + hashtag + list), notifications (list + dismiss + clear + unread count), search (v2 full-text), media (upload + update), lists (CRUD + members), polls (view + vote), conversations (list + read + delete), trends (tags + statuses + links), filters v2 (CRUD + keywords), bookmarks, favourites, mutes, blocks, follow requests, suggestions, instance info, scheduled statuses (CRUD), markers (get + save), reports (create), featured tags (CRUD + suggestions), announcements (list + dismiss), endorsements, preferences, admin accounts (list + get + approve + reject + action + unsuspend + unsilence), admin domain blocks (CRUD)
Missing: streaming WebSocket, email confirmations, canonical email blocks, ip blocks, dimensions, measures, retention, trends admin, admin reports, admin audit log
How do you configure the Mastodon DADL?
- Open your Mastodon instance (e.g. https://mastodon.social)
- Go to Preferences → Development → New Application
- Enter an application name (e.g. 'ToolMesh')
- Select required scopes: read, write (or granular scopes as needed)
- Click 'Submit' to create the application
- Copy the 'Your access token' value — this is your Bearer token
Environment variable: CREDENTIAL_MASTODON_ACCESS_TOKEN
The base_url must be set to the user's Mastodon instance. Each instance is independent — tokens from mastodon.social do not work on other instances. For app-level access (public data only), use OAuth2 client_credentials grant. For user-level access, use the authorization_code grant or generate a token via the web UI under Preferences → Development.
How do you install the Mastodon MCP server with ToolMesh?
Add to your backends.yaml:
- name: mastodon
transport: rest
dadl: mastodon.dadl
url: "https://mastodon.social"
Set the credential:
CREDENTIAL_MASTODON_ACCESS_TOKEN=your-token-hereWhat 115 tools does the Mastodon DADL expose?
GETget_instanceGet server information including version, configuration, usage stats, rules, and supported featuresGETget_instance_peersList domains that this instance is aware of (connected via federation)GETget_instance_activityGet weekly activity statistics (statuses, logins, registrations)GETget_instance_rulesList server rules displayed on the about pageGETget_instance_extended_descriptionGet the extended description of the instance (admin-defined HTML)GETverify_credentialsVerify the access token and get the authenticated user's accountPATCHupdate_credentialsUpdate the authenticated user's display name, bio, avatar, header, fields, and privacy settingsGETget_accountView a profile by account IDGETlookup_accountLookup an account by WebFinger address (user@domain or local username)GETget_account_statusesGet statuses posted by the given accountGETget_account_followersList accounts that follow the given accountGETget_account_followingList accounts that the given account followsGETget_relationshipsCheck relationship (following, blocked, muted, etc.) with one or more accountsGETget_familiar_followersFind mutual followers between you and given accountsGETsearch_accountsSearch for accounts by username or display namePOSTfollow_accountFollow an accountPOSTunfollow_accountUnfollow an accountPOSTremove_followerRemove an account from your followersPOSTblock_accountBlock an accountPOSTunblock_accountUnblock an accountPOSTmute_accountMute an account (hide from timelines and optionally notifications)POSTunmute_accountUnmute an accountPOSTset_account_noteSet a private note on an account (only visible to you)POSTcreate_statusCreate a new status (post/toot). Requires status text or media_ids.GETget_statusView a single status by IDPUTedit_statusEdit an existing statusDELETEdelete_statusDelete a status. Returns the deleted status with a text field for redraft.GETget_status_contextGet the thread context — ancestors (parents) and descendants (replies) of a statusGETget_status_sourceGet the plaintext source of a status for editingGETget_status_historyGet the edit history of a statusPOSTtranslate_statusTranslate a status into the user's language (if translation is supported by the instance)GETget_reblogged_byList accounts that boosted/reblogged a statusGETget_favourited_byList accounts that favourited a statusPOSTfavourite_statusFavourite/like a statusPOSTunfavourite_statusUndo favourite on a statusPOSTreblog_statusBoost/reblog a status to your followersPOSTunreblog_statusUndo a boost/reblogPOSTbookmark_statusBookmark a status (private, only visible to you)POSTunbookmark_statusRemove a status from your bookmarksPOSTmute_statusMute notifications for a status threadPOSTunmute_statusUnmute notifications for a status threadPOSTpin_statusPin a status to your profilePOSTunpin_statusUnpin a status from your profileGETtimeline_homeGet home timeline (statuses from followed accounts and hashtags)GETtimeline_publicGet public timeline (federated or local)GETtimeline_hashtagGet statuses with the given hashtagGETtimeline_listGet timeline for a specific listGETlist_notificationsList notifications (mentions, favourites, boosts, follows, polls, etc.)GETget_notificationGet a single notification by IDPOSTdismiss_notificationDismiss a single notificationPOSTclear_notificationsDismiss all notifications (irreversible)GETget_unread_notification_countGet count of unread notificationsGETsearch_v2Full-text search across accounts, statuses, and hashtags. Returns { accounts, statuses, hashtags } arrays.POSTupload_mediaUpload a media attachment (image, video, audio). Returns 200 or 202 (processing). Attach to a status via media_ids.GETget_mediaCheck media attachment processing status. Returns 200 when ready, 206 when still processing.PUTupdate_mediaUpdate media description or focal point (before attaching to a status)GETget_pollView a poll and its current resultsPOSTvote_pollVote on a pollGETlist_listsGet all lists created by the authenticated userGETget_listGet a single list by IDPOSTcreate_listCreate a new listPUTupdate_listUpdate a list's title or settingsDELETEdelete_listDelete a listGETget_list_accountsList accounts that are members of a listPOSTadd_list_accountsAdd accounts to a list (must be accounts you already follow)DELETEremove_list_accountsRemove accounts from a listGETlist_conversationsList direct message conversationsDELETEdelete_conversationRemove a conversation from your list (does not delete messages)POSTmark_conversation_readMark a conversation as readGETtrending_tagsGet trending hashtags over the past weekGETtrending_statusesGet trending statusesGETtrending_linksGet trending links (news articles shared frequently)GETlist_bookmarksList bookmarked statusesGETlist_favouritesList favourited statusesGETlist_muted_accountsList muted accountsGETlist_blocked_accountsList blocked accountsGETlist_follow_requestsList pending follow requestsPOSTauthorize_follow_requestAccept a pending follow requestPOSTreject_follow_requestReject a pending follow requestGETget_suggestionsGet follow suggestions (staff picks and accounts based on past interactions)DELETEremove_suggestionRemove an account from follow suggestionsGETlist_filtersList all content filtersGETget_filterGet a single filter by IDPOSTcreate_filterCreate a content filter with keywordsPUTupdate_filterUpdate a content filterDELETEdelete_filterDelete a content filterPOSTcreate_appRegister a new OAuth application. Returns client_id and client_secret.GETverify_app_credentialsVerify that the app token is valid and get application infoGETlist_scheduled_statusesList scheduled statuses (posts queued for future publication via scheduled_at)GETget_scheduled_statusGet a single scheduled status by IDPUTupdate_scheduled_statusUpdate the scheduled publication time of a statusDELETEdelete_scheduled_statusCancel and delete a scheduled statusGETget_markersGet saved reading positions for home timeline and/or notificationsPOSTsave_markersSave reading positions for home timeline and/or notificationsPOSTcreate_reportReport an account to instance moderatorsGETlist_featured_tagsList hashtags featured on your profilePOSTcreate_featured_tagFeature a hashtag on your profileDELETEdelete_featured_tagRemove a featured hashtag from your profileGETget_featured_tag_suggestionsGet suggested hashtags to feature (based on your most used tags)GETlist_announcementsList server announcements (active and recent)POSTdismiss_announcementMark an announcement as read/dismissedGETlist_endorsementsList accounts endorsed (featured) on your profileGETget_preferencesGet user preferences (default visibility, language, sensitive flag, expand media, expand spoilers)GETadmin_list_accountsList accounts with admin-level detail (email, IP, status). Requires admin:read:accounts scope.GETadmin_get_accountGet admin-level detail for a single accountPOSTadmin_approve_accountApprove a pending account registrationPOSTadmin_reject_accountReject a pending account registrationPOSTadmin_disable_accountPerform a moderation action on an account (disable, silence, suspend, none)POSTadmin_unsuspend_accountUnsuspend a suspended accountPOSTadmin_unsilence_accountUnsilence a silenced accountGETadmin_list_domain_blocksList blocked domains. Requires admin:read:domain_blocks scope.GETadmin_get_domain_blockGet a single domain block by IDPOSTadmin_create_domain_blockBlock a domain from federating. Requires admin:write:domain_blocks scope.PUTadmin_update_domain_blockUpdate a domain blockDELETEadmin_delete_domain_blockRemove a domain block (re-enable federation)