Skip to content

Quick Start

Jump to bottom
Cameron Rye edited this page Nov 16, 2025 · 1 revision

Quick Start Guide

Get up and running with ActivityPub MCP Server in minutes!

1. Installation

Choose your preferred installation method:

# Quick install with npx (recommended)
npx activitypub-mcp install

# Or install globally
npm install -g activitypub-mcp

# Or clone from source
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm install
npm run build

2. Start the MCP Server

# If installed globally
activitypub-mcp

# If installed locally
npx activitypub-mcp

# If cloned from source
npm run mcp

The server will start and listen for MCP connections via stdio.

3. Test with MCP Inspector

The MCP Inspector is a great tool for testing and exploring the server:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Connect to the server
mcp-inspector

In the inspector:

  1. Select "stdio" as the transport
  2. Enter the command: npx activitypub-mcp (or your installation path)
  3. Click "Connect"

4. Try Your First Commands

Discover an Actor

Use the discover-actor tool to find a fediverse user:

{
  "name": "discover-actor",
  "arguments": {
    "identifier": "Gargron@mastodon.social"
  }
}

Fetch a Timeline

Get recent posts from a user:

{
  "name": "fetch-timeline",
  "arguments": {
    "identifier": "Gargron@mastodon.social",
    "limit": 10
  }
}

Get Instance Information

Learn about a fediverse instance:

{
  "name": "get-instance-info",
  "arguments": {
    "domain": "mastodon.social"
  }
}

Discover Instances

Find fediverse instances by topic:

{
  "name": "discover-instances",
  "arguments": {
    "topic": "technology",
    "size": "medium"
  }
}

5. Integrate with Claude Desktop

To use with Claude Desktop, add this to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"]
    }
  }
}

Restart Claude Desktop to load the server.

6. Explore with Prompts

Try the built-in prompts for guided exploration:

Explore the Fediverse

{
  "name": "explore-fediverse",
  "arguments": {
    "interests": "technology and programming",
    "instanceType": "mastodon"
  }
}

Compare Instances

{
  "name": "compare-instances",
  "arguments": {
    "instances": "mastodon.social, fosstodon.org, hachyderm.io",
    "criteria": "community size and focus"
  }
}

Discover Content

{
  "name": "discover-content",
  "arguments": {
    "topic": "artificial intelligence",
    "contentType": "people"
  }
}

Common Use Cases

Find Interesting People

  1. Use discover-instances to find instances about your interests
  2. Use get-instance-info to learn about the instance
  3. Use search-instance to find users on that instance
  4. Use discover-actor to get detailed info about users
  5. Use fetch-timeline to see their recent posts

Explore a Topic

  1. Use discover-instances with a topic filter
  2. Use search-instance on relevant instances
  3. Use fetch-timeline to see content from interesting users

Compare Communities

  1. Use discover-instances to find instances
  2. Use get-instance-info for each instance
  3. Use the compare-instances prompt for guided comparison

Next Steps

Made with ❤️ by Cameron Rye

Clone this wiki locally