MCP Tools Reference

Complete reference for all Model Context Protocol tools provided by the ActivityPub MCP Server. These tools enable LLMs to interact with the fediverse.

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 identifier in WebFinger format (@user@domain) or ActivityPub URL

Examples

# WebFinger format
discover-actor @mastodon@mastodon.social

# ActivityPub URL
discover-actor https://mastodon.social/users/mastodon

# Profile URL
discover-actor https://mastodon.social/@mastodon

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

Discover popular fediverse instances by category, topic, or size.

Parameters

Name Type Required Description
category enum No Type of fediverse software: "mastodon", "pleroma", "misskey", "peertube", "pixelfed", "lemmy", or "all"
topic string No Topic or interest to search for (e.g., "technology", "art", "gaming")
size enum No Instance size preference: "small", "medium", or "large"
region string No Geographic region or language
beginnerFriendly boolean No Show only beginner-friendly instances

Examples

# Find Mastodon instances
discover-instances --category mastodon

# Find technology-focused instances
discover-instances --topic technology

# Find small, beginner-friendly instances
discover-instances --size small --beginnerFriendly true

# Find instances in a specific region
discover-instances --region europe

recommend-instances

Get personalized fediverse instance recommendations based on interests.

Parameters

Name Type Required Description
interests array Yes List of your interests or topics (e.g., ["technology", "opensource", "privacy"])

Examples

# Get recommendations based on interests
recommend-instances --interests ["technology", "opensource"]

# Multiple interests
recommend-instances --interests ["art", "photography", "design"]

Response

Returns personalized instance recommendations with:

  • Instance domain and name
  • Match score based on interests
  • Instance description and focus
  • User statistics
  • Registration status

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

search-instance

Search for content on a specific fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain (e.g., example.social)
query string Yes Search query
type enum No Type of content to search for: "accounts", "statuses", or "hashtags" (default: "accounts")

Examples

# Search for accounts
search-instance mastodon.social "opensource"

# Search for posts/statuses
search-instance fosstodon.org "linux" --type statuses

# Search for hashtags
search-instance pixelfed.social "photography" --type hashtags

Response

Returns search results based on type:

  • accounts: User profiles matching the query
  • statuses: Posts/toots containing the search terms
  • hashtags: Hashtags matching the query

Timeline Tools

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

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

get-local-timeline

Get the local public timeline from a fediverse instance (posts from local users only).

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)
maxId string No Return results older than this ID (for pagination)

Examples

# Get local timeline
get-local-timeline fosstodon.org

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

get-federated-timeline

Get the federated public timeline from a fediverse instance (posts from all connected instances).

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)
maxId string No Return results older than this ID (for pagination)

Examples

# Get federated timeline
get-federated-timeline 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-accounts

Search for accounts/users on a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain to search
query string Yes Search query (username or display name)
limit number No Number of results (default: 20, max: 40)

Examples

# Search for accounts
search-accounts mastodon.social "developer"

search-hashtags

Search for hashtags on a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain to search
query string Yes Search query (hashtag name without #)
limit number No Number of results (default: 20, max: 40)

Examples

# Search for hashtags
search-hashtags mastodon.social "programming"

search-posts

Search for posts/statuses on a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain to search
query string Yes Search query (keywords or hashtag)
limit number No Number of results (default: 20, max: 40)

Examples

# Search for posts
search-posts mastodon.social "typescript tutorial"

search NEW

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 Yes Instance domain to search
query string Yes Search query
type enum No Filter results: "all", "accounts", "posts", "hashtags" (default: "all")
limit number No Results per type (default: 20, max: 40)
resolve boolean No Attempt WebFinger lookup for remote accounts

Examples

# Search everything
search mastodon.social "programming"

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

# Search with remote lookup
search fosstodon.org "@user@mastodon.social" --resolve true

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

Batch Tools

Tools for fetching multiple items in a single request.

batch-fetch-actors

Fetch multiple actors in a single request for efficiency.

Parameters

Name Type Required Description
identifiers array Yes Array of actor identifiers (e.g., ["user1@mastodon.social", "user2@fosstodon.org"])

Examples

# Fetch multiple actors
batch-fetch-actors --identifiers ["user1@mastodon.social", "user2@fosstodon.org"]

batch-fetch-posts

Fetch multiple posts in a single request for efficiency.

Parameters

Name Type Required Description
urls array Yes Array of post URLs

Examples

# Fetch multiple posts
batch-fetch-posts --urls ["https://mastodon.social/@user/123", "https://fosstodon.org/@user/456"]

Live Discovery Tools

Tools for real-time discovery using external APIs.

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"
limit number No Number of results (default: 20, max: 50)

Examples

# Find Mastodon instances
discover-instances-live --software mastodon

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

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

Utility Tools

Additional tools for server management and debugging.

health-check

Check the health status of the ActivityPub MCP server.

Parameters

Name Type Required Description
includeMetrics boolean No Include detailed performance metrics in the response

Examples

# Basic health check
health-check

# Include detailed metrics
health-check --includeMetrics true

Response

Returns server status including:

  • Server uptime
  • Memory usage
  • Health status (healthy/degraded/unhealthy)
  • Optional: Detailed performance metrics

performance-metrics

Get detailed performance metrics for the ActivityPub MCP server.

Parameters

Name Type Required Description
operation string No Specific operation to get metrics for (e.g., 'discover-actor')

Examples

# Get all performance metrics
performance-metrics

# Get metrics for a specific operation
performance-metrics --operation discover-actor

Response

Returns performance data including:

  • Request counts by operation
  • Average response times
  • Success/failure rates
  • Cache hit rates
  • Resource utilization

Authenticated Write Tools v1.1.0

Tools for authenticated write operations. Requires OAuth token configuration. See the Configuration Guide for setup instructions.

Account Management

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

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

reply-to-post

Reply to an existing post.

Parameters

Name Type Required Description
postUrl string Yes URL of the post to reply to
content string Yes The reply content
visibility enum No Reply visibility (defaults to original post's visibility)
spoilerText string No Content warning/spoiler text

Examples

# Reply to a post
reply-to-post --postUrl "https://mastodon.social/@user/123456" --content "Great point!"

delete-post

Delete one of your own posts.

Parameters

Name Type Required Description
postId string Yes ID of the post to delete

Examples

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

Interaction Tools

boost-post / unboost-post

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

Parameters

Name Type Required Description
postUrl string Yes URL of the post to boost/unboost

Examples

# Boost a post
boost-post --postUrl "https://mastodon.social/@user/123456"

# Remove boost
unboost-post --postUrl "https://mastodon.social/@user/123456"

favourite-post / unfavourite-post

Favourite (like) or unfavourite a post.

Parameters

Name Type Required Description
postUrl string Yes URL of the post to favourite/unfavourite

Examples

# Favourite a post
favourite-post --postUrl "https://mastodon.social/@user/123456"

# Remove favourite
unfavourite-post --postUrl "https://mastodon.social/@user/123456"

bookmark-post / unbookmark-post

Bookmark or unbookmark a post for later reference.

Parameters

Name Type Required Description
postUrl string Yes URL of the post to bookmark/unbookmark

Examples

# Bookmark a post
bookmark-post --postUrl "https://mastodon.social/@user/123456"

# Remove bookmark
unbookmark-post --postUrl "https://mastodon.social/@user/123456"

Relationship Tools

get-relationship NEW

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

Parameters

Name Type Required Description
accountIds array Yes Array of account IDs to check relationship status

Examples

# Check relationship with accounts
get-relationship --accountIds ["12345", "67890"]

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
identifier string Yes Account identifier (@user@domain or URL)

Examples

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

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

mute-account / unmute-account

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

Parameters

Name Type Required Description
identifier string Yes Account identifier (@user@domain or URL)
duration number No Mute duration in seconds (0 for permanent, mute-account only)
notifications boolean No Also mute notifications (default: true, mute-account only)

Examples

# Mute an account permanently
mute-account --identifier "@user@mastodon.social"

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

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

block-account / unblock-account

Block or unblock an account (prevents all interactions).

Parameters

Name Type Required Description
identifier string Yes Account identifier (@user@domain or URL)

Examples

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

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

Authenticated Timelines

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", "reblog", "favourite", "follow", "poll", "follow_request"
excludeTypes array No Exclude specific notification types

Examples

# Get all notifications
get-notifications

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

# Exclude follow notifications
get-notifications --excludeTypes ["follow", "follow_request"]

get-bookmarks

Get your bookmarked posts.

Parameters

Name Type Required Description
limit number No Number of bookmarks (default: 20, max: 40)
maxId string No Return results older than this ID

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)
maxId string No Return results older than this ID

Examples

# Get favourited posts
get-favourites --limit 40

Poll Tools NEW

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 NEW

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 Local file path or URL of the media to upload
description string No Alt text description for accessibility (highly recommended)
focus string No Focal point as "x,y" where each value is -1.0 to 1.0 (determines crop center)

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" --focus "0.0,0.5"

# Upload from URL
upload-media --filePath "https://example.com/image.jpg" --description "External image"

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 NEW

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)
maxId string No Return results older than this ID (pagination)

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 (e.g., "2026-02-14T18:00:00.000Z")

Examples

# Reschedule a post
update-scheduled-post --scheduledPostId "123" --scheduledAt "2026-02-14T18:00:00.000Z"

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"

Content Export Tools v1.1.0

Tools for exporting fediverse content in various formats (JSON, Markdown, CSV).

export-timeline

Export an actor's timeline to a file in your chosen format.

Parameters

Name Type Required Description
identifier string Yes Actor identifier (@user@domain or URL)
format enum No Export format: "json", "markdown", "csv" (default: "json")
limit number No Number of posts to export (default: 100, max: 500)
includeBoosts boolean No Include boosted posts (default: true)
includeReplies boolean No Include replies (default: true)

Examples

# Export timeline as JSON
export-timeline --identifier "@user@mastodon.social"

# Export as Markdown, original posts only
export-timeline --identifier "@user@mastodon.social" --format markdown --includeBoosts false --includeReplies false

# Export as CSV with limit
export-timeline --identifier "@user@mastodon.social" --format csv --limit 200

export-thread

Export a post thread with all ancestors and replies.

Parameters

Name Type Required Description
postUrl string Yes URL of the post
format enum No Export format: "json", "markdown", "csv" (default: "json")
depth number No Max reply depth (default: 3, max: 10)

Examples

# Export thread as JSON
export-thread --postUrl "https://mastodon.social/@user/123456"

# Export as readable Markdown
export-thread --postUrl "https://mastodon.social/@user/123456" --format markdown --depth 5

export-account-info

Export comprehensive account information including profile, stats, and recent activity.

Parameters

Name Type Required Description
identifier string Yes Account identifier (@user@domain or URL)
format enum No Export format: "json", "markdown" (default: "json")
includeTimeline boolean No Include recent posts (default: false)
timelineLimit number No Number of posts if includeTimeline is true (default: 50)

Examples

# Export account info as JSON
export-account-info --identifier "@user@mastodon.social"

# Export with timeline as Markdown
export-account-info --identifier "@user@mastodon.social" --format markdown --includeTimeline true

export-hashtag

Export posts containing a specific hashtag from an instance.

Parameters

Name Type Required Description
domain string Yes Instance domain to search
hashtag string Yes Hashtag to export (without #)
format enum No Export format: "json", "markdown", "csv" (default: "json")
limit number No Number of posts (default: 100, max: 500)
local boolean No Only local posts (default: false)

Examples

# Export hashtag posts as JSON
export-hashtag --domain mastodon.social --hashtag "programming"

# Export local posts only as Markdown
export-hashtag --domain fosstodon.org --hashtag "opensource" --format markdown --local true

# Export as CSV for analysis
export-hashtag --domain mastodon.social --hashtag "rust" --format csv --limit 200

Error Handling

All tools follow consistent error handling patterns:

Validation Errors

Returned when parameters are invalid or missing:

{`{
  "error": "Invalid parameter",
  "message": "Actor identifier must be in @user@domain format or valid URL",
  "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"
}`}

Related Documentation

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