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-trending-hashtags`

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-trending-posts`

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

`search`

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"
}

MCP Resources — Learn about the resources exposed by the server
Basic Usage Guide — See these tools in action with practical examples
Troubleshooting — Solutions for common tool-related issues

MCP Tools Reference

Discovery Tools

discover-actor

Parameters

Examples

Response

Information Tools

get-instance-info

Parameters

Examples

Response

fetch-timeline

Parameters

Examples

Response

Timeline Tools

get-public-timeline

Parameters

Examples

get-trending-hashtags

Parameters

Examples

get-trending-posts

Parameters

Examples

Content Tools

get-post-thread

Parameters

Examples

search

Parameters

Examples

Response

Live Instance Discovery

discover-instances (live)

Parameters

Examples

Authenticated Tools

Account Management (authenticated read — no ENABLE_WRITES required)

list-accounts

Parameters

Examples

Response

switch-account

Parameters

Examples

verify-account

Parameters

Examples

Response

Posting Tools

post-status

Parameters

Examples

reply-to-post

Parameters

Examples

delete-post

Parameters

Examples

Interaction Tools

boost-post / unboost-post

Parameters

Examples

favourite-post / unfavourite-post

Parameters

Examples

bookmark-post / unbookmark-post

Parameters

Examples

Relationship Tools

get-relationship

Parameters

Examples

Response

follow-account / unfollow-account

Parameters

Examples

mute-account / unmute-account

Parameters

`discover-actor`

`get-instance-info`

`fetch-timeline`

`get-public-timeline`

`get-trending-hashtags`

`get-trending-posts`

`get-post-thread`

`search`

`discover-instances` (live)

Account Management (authenticated read — no `ENABLE_WRITES` required)

`list-accounts`

`switch-account`

`verify-account`

`post-status`

`reply-to-post`

`delete-post`

`boost-post` / `unboost-post`

`favourite-post` / `unfavourite-post`

`bookmark-post` / `unbookmark-post`

`get-relationship`

`follow-account` / `unfollow-account`

`mute-account` / `unmute-account`

`block-account` / `unblock-account`

Authenticated Timelines (authenticated reads — no `ENABLE_WRITES` required)

`get-home-timeline`

`get-notifications`

`get-bookmarks`

`get-favourites`

`vote-on-poll`

`upload-media`

`get-scheduled-posts`

`update-scheduled-post`

`cancel-scheduled-post`