Skip to content

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

Credits: Dunkel Cloud GmbHUpdated: 2026-04-08

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

Last reviewed: 2026-04-09

How do you configure the Mastodon DADL?

  1. Open your Mastodon instance (e.g. https://mastodon.social)
  2. Go to Preferences → Development → New Application
  3. Enter an application name (e.g. 'ToolMesh')
  4. Select required scopes: read, write (or granular scopes as needed)
  5. Click 'Submit' to create the application
  6. Copy the 'Your access token' value — this is your Bearer token

Environment variable: CREDENTIAL_MASTODON_ACCESS_TOKEN

Authentication docs ↗

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-here

What 115 tools does the Mastodon DADL expose?

GETget_instanceGet server information including version, configuration, usage stats, rules, and supported features
GETget_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 page
GETget_instance_extended_descriptionGet the extended description of the instance (admin-defined HTML)
GETverify_credentialsVerify the access token and get the authenticated user's account
PATCHupdate_credentialsUpdate the authenticated user's display name, bio, avatar, header, fields, and privacy settings
GETget_accountView a profile by account ID
GETlookup_accountLookup an account by WebFinger address (user@domain or local username)
GETget_account_statusesGet statuses posted by the given account
GETget_account_followersList accounts that follow the given account
GETget_account_followingList accounts that the given account follows
GETget_relationshipsCheck relationship (following, blocked, muted, etc.) with one or more accounts
GETget_familiar_followersFind mutual followers between you and given accounts
GETsearch_accountsSearch for accounts by username or display name
POSTfollow_accountFollow an account
POSTunfollow_accountUnfollow an account
POSTremove_followerRemove an account from your followers
POSTblock_accountBlock an account
POSTunblock_accountUnblock an account
POSTmute_accountMute an account (hide from timelines and optionally notifications)
POSTunmute_accountUnmute an account
POSTset_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 ID
PUTedit_statusEdit an existing status
DELETEdelete_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 status
GETget_status_sourceGet the plaintext source of a status for editing
GETget_status_historyGet the edit history of a status
POSTtranslate_statusTranslate a status into the user's language (if translation is supported by the instance)
GETget_reblogged_byList accounts that boosted/reblogged a status
GETget_favourited_byList accounts that favourited a status
POSTfavourite_statusFavourite/like a status
POSTunfavourite_statusUndo favourite on a status
POSTreblog_statusBoost/reblog a status to your followers
POSTunreblog_statusUndo a boost/reblog
POSTbookmark_statusBookmark a status (private, only visible to you)
POSTunbookmark_statusRemove a status from your bookmarks
POSTmute_statusMute notifications for a status thread
POSTunmute_statusUnmute notifications for a status thread
POSTpin_statusPin a status to your profile
POSTunpin_statusUnpin a status from your profile
GETtimeline_homeGet home timeline (statuses from followed accounts and hashtags)
GETtimeline_publicGet public timeline (federated or local)
GETtimeline_hashtagGet statuses with the given hashtag
GETtimeline_listGet timeline for a specific list
GETlist_notificationsList notifications (mentions, favourites, boosts, follows, polls, etc.)
GETget_notificationGet a single notification by ID
POSTdismiss_notificationDismiss a single notification
POSTclear_notificationsDismiss all notifications (irreversible)
GETget_unread_notification_countGet count of unread notifications
GETsearch_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 results
POSTvote_pollVote on a poll
GETlist_listsGet all lists created by the authenticated user
GETget_listGet a single list by ID
POSTcreate_listCreate a new list
PUTupdate_listUpdate a list's title or settings
DELETEdelete_listDelete a list
GETget_list_accountsList accounts that are members of a list
POSTadd_list_accountsAdd accounts to a list (must be accounts you already follow)
DELETEremove_list_accountsRemove accounts from a list
GETlist_conversationsList direct message conversations
DELETEdelete_conversationRemove a conversation from your list (does not delete messages)
POSTmark_conversation_readMark a conversation as read
GETtrending_tagsGet trending hashtags over the past week
GETtrending_statusesGet trending statuses
GETtrending_linksGet trending links (news articles shared frequently)
GETlist_bookmarksList bookmarked statuses
GETlist_favouritesList favourited statuses
GETlist_muted_accountsList muted accounts
GETlist_blocked_accountsList blocked accounts
GETlist_follow_requestsList pending follow requests
POSTauthorize_follow_requestAccept a pending follow request
POSTreject_follow_requestReject a pending follow request
GETget_suggestionsGet follow suggestions (staff picks and accounts based on past interactions)
DELETEremove_suggestionRemove an account from follow suggestions
GETlist_filtersList all content filters
GETget_filterGet a single filter by ID
POSTcreate_filterCreate a content filter with keywords
PUTupdate_filterUpdate a content filter
DELETEdelete_filterDelete a content filter
POSTcreate_appRegister a new OAuth application. Returns client_id and client_secret.
GETverify_app_credentialsVerify that the app token is valid and get application info
GETlist_scheduled_statusesList scheduled statuses (posts queued for future publication via scheduled_at)
GETget_scheduled_statusGet a single scheduled status by ID
PUTupdate_scheduled_statusUpdate the scheduled publication time of a status
DELETEdelete_scheduled_statusCancel and delete a scheduled status
GETget_markersGet saved reading positions for home timeline and/or notifications
POSTsave_markersSave reading positions for home timeline and/or notifications
POSTcreate_reportReport an account to instance moderators
GETlist_featured_tagsList hashtags featured on your profile
POSTcreate_featured_tagFeature a hashtag on your profile
DELETEdelete_featured_tagRemove a featured hashtag from your profile
GETget_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/dismissed
GETlist_endorsementsList accounts endorsed (featured) on your profile
GETget_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 account
POSTadmin_approve_accountApprove a pending account registration
POSTadmin_reject_accountReject a pending account registration
POSTadmin_disable_accountPerform a moderation action on an account (disable, silence, suspend, none)
POSTadmin_unsuspend_accountUnsuspend a suspended account
POSTadmin_unsilence_accountUnsilence a silenced account
GETadmin_list_domain_blocksList blocked domains. Requires admin:read:domain_blocks scope.
GETadmin_get_domain_blockGet a single domain block by ID
POSTadmin_create_domain_blockBlock a domain from federating. Requires admin:write:domain_blocks scope.
PUTadmin_update_domain_blockUpdate a domain block
DELETEadmin_delete_domain_blockRemove a domain block (re-enable federation)