MCP Tools Reference

Read-only by default. All tools listed here are available without any special configuration. Write tools (post, reply, follow, boost, etc.) are only registered when ACTIVITYPUB_ENABLE_WRITES=true is set in the server environment. See the Configuration Options page for details.

Discovery Tools

Tools for discovering actors, instances, and content across the fediverse.

discover-actor

Discover and get detailed information about fediverse actors (users).

Parameters

Name Type Required Description
identifier string Yes Actor handle in WebFinger format (@user@domain or user@domain). A profile URL is not a valid identifier.

Examples

# WebFinger handle (the only accepted form)
discover-actor @mastodon@mastodon.social

# The leading @ is optional
discover-actor mastodon@mastodon.social

Response

Returns an ActivityPub Actor object with:

  • Actor ID and type
  • Display name and username
  • Profile information (bio, avatar, etc.)
  • Public key for verification
  • Endpoints (inbox, outbox, followers, etc.)

discover-instances is documented under Live Instance Discovery below — it queries instances.social for real-time data.

Information Tools

Tools for getting information about instances, timelines, and content.

get-instance-info

Get detailed information about a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain name (e.g., “mastodon.social”)

Examples

# Get info about Mastodon.social
get-instance-info mastodon.social

# Check a smaller instance
get-instance-info fosstodon.org

Response

Returns instance metadata including:

  • Instance name and description
  • Software version and type
  • User and post statistics
  • Instance rules and policies
  • Contact information
  • Supported features

fetch-timeline

Fetch recent posts from any actor’s timeline in the fediverse.

Parameters

Name Type Required Description
identifier string Yes Actor identifier (e.g., user@example.social)
limit number No Number of posts to fetch (default: 20, max: 50)

Examples

# Get recent posts from an actor
fetch-timeline user@mastodon.social

# Limit to 10 posts
fetch-timeline admin@fosstodon.org --limit 10

Response

Returns timeline data including:

  • Array of recent posts/activities
  • Post content and metadata
  • Author information
  • Engagement metrics (likes, boosts, replies)
  • Media attachments

Timeline Tools

Tools for accessing public timelines and trending content from fediverse instances.

get-public-timeline

Get the public timeline from a fediverse instance — local posts only, or the full federated feed.

Parameters

Name Type Required Description
domain string Yes Instance domain (e.g., “mastodon.social”)
scope enum No Timeline scope: “local” (posts from the instance only) or “federated” (posts from all connected instances). Default: “federated”
limit number No Number of posts to fetch (default: 20, max: 40)
maxId string No Return results older than this ID (for pagination)

Examples

# Get local timeline (that instance's own posts) — scope must be set explicitly
get-public-timeline fosstodon.org --scope local

# Get federated timeline (the default)
get-public-timeline mastodon.social --scope federated

# Paginate results
get-public-timeline fosstodon.org --maxId 123456789

Get currently trending hashtags on a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain (e.g., “mastodon.social”)
limit number No Number of hashtags to fetch (default: 20, max: 40)

Examples

# Get trending hashtags
get-trending-hashtags mastodon.social

# Limit results
get-trending-hashtags fosstodon.org --limit 10

Get currently trending posts on a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain (e.g., “mastodon.social”)
limit number No Number of posts to fetch (default: 20, max: 40)

Examples

# Get trending posts
get-trending-posts mastodon.social

Content Tools

Tools for fetching and searching content in the fediverse.

get-post-thread

Fetch a post and its full conversation thread including replies and parent posts.

Parameters

Name Type Required Description
postUrl string Yes The URL of the post to fetch the thread for
depth number No How many levels of nested replies to fetch (default: 2, max: 5)
maxReplies number No Maximum number of replies to fetch (default: 50, max: 100)

Examples

# Get post thread
get-post-thread https://mastodon.social/@user/123456789

# Get deeper thread
get-post-thread https://mastodon.social/@user/123456789 --depth 3 --maxReplies 100

Unified search across accounts, posts, and hashtags in a single query. Combines all search types with optional filtering.

Parameters

Name Type Required Description
domain string No Instance domain to search. Defaults to mastodon.social.
query string Yes Search query
type enum No Filter results: “all”, “accounts”, “posts”, “hashtags” (default: “all”)
limit number No Results per type (default: 10, max: 40)

Examples

# Search everything
search mastodon.social "programming"

# Search only accounts
search mastodon.social "developer" --type accounts

# Search a specific instance
search fosstodon.org "@user@mastodon.social"

Response

Returns combined results with:

  • Accounts section with profile summaries
  • Posts section with content previews
  • Hashtags section with usage statistics
  • Result counts for each category

Live Instance Discovery

Real-time instance discovery using external APIs. The discover-instances tool queries instances.social for live data with advanced filtering.

discover-instances (live)

Discover fediverse instances in real-time using the instances.social API with advanced filtering.

Parameters

Name Type Required Description
software enum No Filter by software: “mastodon”, “pleroma”, “misskey”, “pixelfed”, “lemmy”, “peertube”, “any”
language string No Filter by language code (e.g., “en”, “de”, “ja”)
minUsers number No Minimum number of users
maxUsers number No Maximum number of users
openRegistrations boolean No Only show instances with open registrations
sortBy enum No Sort by: “users”, “statuses”, “connections”, “name”
sortOrder enum No Sort direction: “asc” or “desc” (default: “desc”)
limit number No Number of results (default: 20, max: 50)

Examples

# Find Mastodon instances
discover-instances --software mastodon

# Find large English instances with open registration
discover-instances --language en --minUsers 10000 --openRegistrations true

# Find small community instances
discover-instances --maxUsers 5000 --sortBy users

Authenticated Tools

These tools require an authenticated account. The recommended way to authenticate is the CLI flow — activitypub-mcp login <instance> (Mastodon OAuth2 / Misskey MiAuth), which stores credentials in the on-disk credential store; alternatively set ACTIVITYPUB_ACCOUNTS (or ACTIVITYPUB_DEFAULT_INSTANCE + ACTIVITYPUB_DEFAULT_TOKEN). See the Authentication and Configuration Options pages for setup instructions.

They split into two tiers:

  • Authenticated reads — always available with an account, no ACTIVITYPUB_ENABLE_WRITES needed: list-accounts, switch-account, verify-account, get-home-timeline, get-notifications, get-bookmarks, get-favourites, get-relationship, and get-scheduled-posts. (Reading your own home timeline or notifications does not require enabling writes.)
  • Write/mutation tools — disabled by default, registered only when ACTIVITYPUB_ENABLE_WRITES=true is set in the server environment: post-status, reply-to-post, delete-post, the boost/favourite/bookmark pairs, follow-account/mute-account/block-account (and their inverses), vote-on-poll, upload-media, update-scheduled-post, and cancel-scheduled-post.

Some authenticated tools are Mastodon-family only and return an “unsupported on platform” error on Misskey/Foundkey accounts: get-bookmarks, get-favourites, vote-on-poll, and the scheduled-post tools. get-home-timeline, get-notifications, and get-relationship work across both.

Account Management (authenticated read — no ENABLE_WRITES required)

list-accounts

List all configured accounts with their authentication status.

Parameters

None required.

Examples

# List all configured accounts
list-accounts

Response

Returns array of configured accounts with:

  • Account ID and instance domain
  • Username
  • Active status indicator

switch-account

Switch the active account for subsequent authenticated operations.

Parameters

Name Type Required Description
accountId string Yes The ID of the account to switch to

Examples

# Switch to work account
switch-account --accountId work

# Switch to personal account
switch-account --accountId personal

verify-account

Verify the credentials and permissions of the active account.

Parameters

None required. Uses the currently active account.

Examples

# Verify current account credentials
verify-account

Response

Returns verification status with:

  • Account details (username, display name)
  • Instance information
  • Granted OAuth scopes
  • Token validity status

Posting Tools

post-status

Create a new post/status on the fediverse.

Parameters

Name Type Required Description
content string Yes The text content of the post
visibility enum No Post visibility: “public”, “unlisted”, “private”, “direct” (default: “public”)
spoilerText string No Content warning/spoiler text
sensitive boolean No Mark media as sensitive
language string No ISO 639-1 language code (e.g., “en”)
mediaIds string[] No Media attachment IDs from upload-media (max 4 per post, Mastodon limit)
scheduledAt string (ISO 8601) No Schedule the post for a future time (must be in the future; the target instance enforces its own minimum lead time, typically ~5 minutes). Returns a scheduled post — manage with get-scheduled-posts / update-scheduled-post / cancel-scheduled-post.
accountId string No Account ID to post from (defaults to the active account from switch-account)

Examples

# Simple public post
post-status --content "Hello fediverse!"

# Post with content warning
post-status --content "Spoiler discussion here" --spoilerText "Movie spoilers"

# Unlisted post
post-status --content "Only visible to followers" --visibility unlisted

# Post with media (upload first via upload-media)
post-status --content "Look at this!" --mediaIds '["12345"]'

# Schedule a post for later
post-status --content "Happy New Year!" --scheduledAt "2027-01-01T00:00:00Z"

reply-to-post

Reply to an existing post.

Parameters

Name Type Required Description
statusId string Yes The ID of the post to reply to (a bare post ID, not a URL — e.g. from fetch-timeline)
content string Yes The reply content
visibility enum No Reply visibility: “public”, “unlisted”, “private”, “direct”
spoilerText string No Content warning/spoiler text
accountId string No Account ID to reply from (defaults to the active account)

Examples

# Reply to a post (statusId is the bare post ID)
reply-to-post --statusId "123456" --content "Great point!"

delete-post

Delete one of your own posts.

Parameters

Name Type Required Description
statusId string Yes The ID of your post to delete
accountId string No Account ID the post belongs to (defaults to the active account)

Examples

# Delete a post
delete-post --statusId "123456789"

Interaction Tools

boost-post / unboost-post

Boost (reblog) or unboost a post to share it with your followers.

Parameters

Name Type Required Description
statusId string Yes The ID of the post to boost/unboost (a bare post ID, not a URL)
accountId string No Account ID to act from (defaults to the active account)

Examples

# Boost a post
boost-post --statusId "123456"

# Remove boost
unboost-post --statusId "123456"

favourite-post / unfavourite-post

Favourite (like) or unfavourite a post.

Parameters

Name Type Required Description
statusId string Yes The ID of the post to favourite/unfavourite (a bare post ID, not a URL)
accountId string No Account ID to act from (defaults to the active account)

Examples

# Favourite a post
favourite-post --statusId "123456"

# Remove favourite
unfavourite-post --statusId "123456"

bookmark-post / unbookmark-post

Bookmark or unbookmark a post for later reference.

Parameters

Name Type Required Description
statusId string Yes The ID of the post to bookmark/unbookmark (a bare post ID, not a URL)
accountId string No Account ID to act from (defaults to the active account)

Examples

# Bookmark a post
bookmark-post --statusId "123456"

# Remove bookmark
unbookmark-post --statusId "123456"

Relationship Tools

get-relationship

Check your relationship status with one or more accounts (following, followed_by, blocking, muting, etc.).

Parameters

Name Type Required Description
acct string Yes Single account ID or acct handle (e.g. user@instance.social) to check the relationship for. Call once per account.

Examples

# Check relationship with a single account
get-relationship --acct "user@mastodon.social"

# To check multiple accounts, call the tool once per account.

Response

Returns relationship status for each account:

  • following - Whether you follow them
  • followed_by - Whether they follow you
  • blocking - Whether you’ve blocked them
  • muting - Whether you’ve muted them
  • requested - Whether you’ve sent a follow request

follow-account / unfollow-account

Follow or unfollow another account.

Parameters

Name Type Required Description
acct string Yes Account to follow (username@instance, or just username for a local account)
showBoosts boolean No Show boosts from this account (default: true, follow-account only)
notify boolean No Get notified when this account posts (default: false, follow-account only)
accountId string No Your account ID to act from (defaults to the active account)

Examples

# Follow an account
follow-account --acct "user@mastodon.social"

# Unfollow an account
unfollow-account --acct "user@mastodon.social"

mute-account / unmute-account

Mute or unmute an account (hide their posts without unfollowing).

Parameters

Name Type Required Description
acct string Yes Account to mute/unmute (username@instance)
muteNotifications boolean No Also mute notifications (default: true, mute-account only)
duration number No Mute duration in seconds (0 for indefinite, mute-account only)
accountId string No Your account ID to act from (defaults to the active account)

Examples

# Mute an account indefinitely
mute-account --acct "user@mastodon.social"

# Mute for 24 hours
mute-account --acct "user@mastodon.social" --duration 86400

# Unmute an account
unmute-account --acct "user@mastodon.social"

block-account / unblock-account

Block or unblock an account (prevents all interactions).

Parameters

Name Type Required Description
acct string Yes Account to block/unblock (username@instance)
accountId string No Your account ID to act from (defaults to the active account)

Examples

# Block an account
block-account --acct "user@mastodon.social"

# Unblock an account
unblock-account --acct "user@mastodon.social"

Authenticated Timelines (authenticated reads — no ENABLE_WRITES required)

get-home-timeline

Get your authenticated home timeline (posts from followed accounts).

Parameters

Name Type Required Description
limit number No Number of posts to fetch (default: 20, max: 40)
maxId string No Return results older than this ID (pagination)
sinceId string No Return results newer than this ID

Examples

# Get home timeline
get-home-timeline

# Paginate through timeline
get-home-timeline --maxId "123456789" --limit 40

get-notifications

Get your notifications (mentions, follows, boosts, favourites).

Parameters

Name Type Required Description
limit number No Number of notifications (default: 20, max: 40)
types array No Filter by type: “mention”, “status”, “reblog”, “follow”, “follow_request”, “favourite”, “poll”, “update”

Examples

# Get all notifications
get-notifications

# Get only mentions
get-notifications --types ["mention"]

# Filter to mentions and favourites
get-notifications --types ["mention", "favourite"]

get-bookmarks

Get your bookmarked posts.

Parameters

Name Type Required Description
limit number No Number of bookmarks (default: 20, max: 40)

Examples

# Get bookmarks
get-bookmarks --limit 40

get-favourites

Get posts you have favourited.

Parameters

Name Type Required Description
limit number No Number of favourites (default: 20, max: 40)

Examples

# Get favourited posts
get-favourites --limit 40

Poll Tools

vote-on-poll

Vote on a poll attached to a post. Supports single and multiple choice polls.

Parameters

Name Type Required Description
pollId string Yes The ID of the poll to vote on
choices array Yes Array of choice indices (0-based). Single choice polls accept one index, multiple choice can accept several.

Examples

# Vote for option 1 (index 0)
vote-on-poll --pollId "123456" --choices [0]

# Vote for multiple options in a multi-choice poll
vote-on-poll --pollId "123456" --choices [0, 2]

Response

Returns the updated poll with:

  • Current vote counts for each option
  • Visual bar chart of results
  • Your vote confirmation
  • Poll expiration time

Media Tools

upload-media

Upload media files (images, videos, audio) to use in posts. Supports alt text for accessibility.

Parameters

Name Type Required Description
filePath string Yes Absolute path to the file on the machine running the MCP server (not a URL, and not the user’s machine)
description string No Alt text description for accessibility (highly recommended)
focusX number No Horizontal focal point, -1.0 to 1.0 (determines crop center). Must be provided together with focusY.
focusY number No Vertical focal point, -1.0 to 1.0 (determines crop center). Must be provided together with focusX.

Examples

# Upload image with alt text
upload-media --filePath "/path/to/image.jpg" --description "A sunset over mountains"

# Upload with focal point for cropping
upload-media --filePath "/path/to/photo.png" --description "Portrait photo" --focusX 0.0 --focusY 0.5

Response

Returns media attachment details:

  • Media ID (use in post-status --mediaIds)
  • Media type (image, video, audio, gifv)
  • Preview URL
  • Blurhash for placeholders

Scheduling Tools

get-scheduled-posts

List all your pending scheduled posts.

Parameters

Name Type Required Description
limit number No Number of scheduled posts to fetch (default: 20, max: 40)

Examples

# Get all scheduled posts
get-scheduled-posts

# Get with limit
get-scheduled-posts --limit 10

Response

Returns list of scheduled posts with:

  • Scheduled post ID
  • Scheduled publication time
  • Post content and parameters
  • Attached media (if any)

update-scheduled-post

Reschedule a pending post to a new time.

Parameters

Name Type Required Description
scheduledPostId string Yes ID of the scheduled post to update
scheduledAt string Yes New scheduled time in ISO 8601 format. Must be in the future (the target instance enforces its own minimum lead time).

Examples

# Reschedule a post
update-scheduled-post --scheduledPostId "123" --scheduledAt "<ISO 8601 timestamp in the future>"

cancel-scheduled-post

Cancel a scheduled post before it’s published.

Parameters

Name Type Required Description
scheduledPostId string Yes ID of the scheduled post to cancel

Examples

# Cancel a scheduled post
cancel-scheduled-post --scheduledPostId "123"

Error Handling

All tools follow consistent error handling patterns:

Validation Errors

Returned when parameters are invalid or missing:

{
  "error": "Invalid parameter",
  "message": "Invalid identifier format. Expected: user@domain.com or @user@domain.com",
  "code": "INVALID_PARAMETER"
}

Network Errors

Returned when external services are unreachable:

{
  "error": "Network error",
  "message": "Failed to connect to instance: connection timeout",
  "code": "NETWORK_ERROR"
}

Not Found Errors

Returned when requested resources don’t exist:

{
  "error": "Not found",
  "message": "Actor not found or not accessible",
  "code": "NOT_FOUND"
}