Basic Usage Guide

Core Concepts

Fediverse Client

This server acts as a client to existing fediverse servers. You don’t need to run your own ActivityPub server - it connects to existing instances like Mastodon, Pleroma, and Misskey.

MCP Tools

The server provides tools that LLMs can call to perform actions like discovering actors, fetching timelines, and exploring instances.

MCP Resources

The server exposes resources that provide information about the server itself, discovered actors, and cached data.

Essential Tools

Here are the most important tools you’ll use regularly:

discover-actor

Find and get information about fediverse actors (users).

Example:

discover-actor @mastodon@mastodon.social

Returns detailed information about the @mastodon account on mastodon.social

fetch-timeline

Get recent posts from an actor’s timeline. Identify the actor by handle (@user@domain or user@domain) — not by URL.

Example:

fetch-timeline @mastodon@mastodon.social

Retrieves the latest posts from the specified actor

get-instance-info

Get information about a fediverse instance.

Example:

get-instance-info mastodon.social

Returns instance metadata, rules, and statistics

discover-instances

Find fediverse instances by software, language, size, registration status, and sort order. (It filters on instance metadata — it does not take a free-text topic. For topical discovery, use search with --type hashtags or --type accounts.)

Example:

discover-instances --software mastodon --language en --minUsers 1000

Finds Mastodon instances in English with at least 1000 users

Common Workflows

Exploring a New Instance

  1. Get instance information: get-instance-info example.social
  2. Discover popular actors: discover-actor @admin@example.social
  3. Check recent activity: fetch-timeline @admin@example.social

Following an Actor’s Activity

  1. Discover the actor: discover-actor @username@instance.com
  2. Get their recent posts: fetch-timeline @username@instance.com
  3. Check their followers/following (if public)

Finding Communities

  1. Filter instances by software/language/size: discover-instances --software mastodon --language en
  2. Check instance info for each result
  3. Explore popular actors on interesting instances

Tips & Best Practices

Actor Identifiers

Actor tools (discover-actor, fetch-timeline) identify actors by handle, not URL:

  • @username@instance.com - WebFinger format (leading @ optional)
  • username@instance.com - also accepted

A full profile URL (e.g. https://instance.com/users/username) is not a valid identifier for these tools — convert it to the username@instance.com handle first.

Performance

The server caches responses to improve performance:

  • Actor information is cached for 5 minutes
  • Instance info is cached for 1 hour
  • Timeline data is cached for 2 minutes

Privacy

Respect privacy and instance rules:

  • Only access public information
  • Follow instance rate limits
  • Respect user privacy settings

Troubleshooting

If something doesn’t work:

  • Check the actor/instance URL format
  • Verify the instance is accessible
  • Try a different actor or instance

Advanced Usage

Combining Tools

Use multiple tools together for comprehensive exploration:

# First filter instances by software and language
discover-instances --software mastodon --language en

# Then explore each instance
get-instance-info fosstodon.org

# Find interesting actors
discover-actor @admin@fosstodon.org

# Check their activity
fetch-timeline @admin@fosstodon.org

Using with Claude Desktop

Ask Claude to help you explore:

“Help me find interesting technology-focused Mastodon instances and show me what kind of content is popular there.”

Claude will use the MCP tools to discover instances, check their info, and explore popular content.

Next Steps