ActivityPub MCP Server - Fediverse Client

A comprehensive Model Context Protocol (MCP) server that enables LLMs like Claude to explore and interact with the existing Fediverse through standardized MCP tools, resources, and prompts.

🌟 Features

Core Capabilities

• 🌐 Fediverse Client: Interact with existing ActivityPub servers (Mastodon, Pleroma, Misskey, etc.)
• 🔍 WebFinger Discovery: Find and discover actors across the fediverse
• 🤖 MCP Protocol: Complete MCP server with resources, tools, and prompts
• 🧠 LLM-Optimized: Designed specifically for LLM interaction patterns
• 📝 TypeScript: Fully typed with modern TypeScript and ESM
• ⚡ High Performance: Efficient resource management and caching
• 🔒 Secure: Built-in security features and input validation

Fediverse Interaction Features

• ✅ Remote Actor Discovery: Find users on any fediverse instance
• ✅ Timeline Fetching: Get posts from any user's timeline
• ✅ Instance Discovery: Find and explore fediverse instances
• ✅ Instance Information: Get detailed info about any server
• ✅ Search Capabilities: Search for content across instances
• ✅ WebFinger Support: Resolve actor identifiers across the network
• ✅ Multi-Platform Support: Works with Mastodon, Pleroma, Misskey, and more
• ✅ Follower/Following Lists: Access social connections

MCP Features

• 📚 Resources: Access remote ActivityPub data (actors, timelines, instance info)
• 🔧 Tools: Discover and interact with fediverse content
• 💬 Prompts: Templates for fediverse exploration and discovery
• 🔄 Completions: Context-aware argument completion
• 🎯 Sampling: LLM integration for content discovery
• 📊 Monitoring: Built-in logging and performance metrics

🚀 Quick Start

Prerequisites

• Node.js 18+ (LTS recommended)
• npm or yarn package manager
• Git for cloning the repository

Cross-Platform Support

This project works on Windows, macOS, and Linux with automatic platform detection and appropriate script selection.

One-Click Installation

For the fastest setup, use our automated installation script:

Universal (All Platforms)

# Install directly with npx (recommended)
npx activitypub-mcp install

# Or clone and run setup
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm run setup

Platform-Specific Installation

Windows (PowerShell):

# Clone and setup
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm run setup:windows

# Or run PowerShell script directly
.\scripts\setup.ps1

macOS/Linux (Bash):

# Clone and setup
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm run setup:unix

# Or run bash script directly
bash scripts/setup.sh

Manual Installation

1. Clone and install dependencies:

git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp
npm install

2. Configure environment:

Windows:

# Copy environment template
copy .env.example .env

# Edit configuration (optional)
notepad .env

macOS/Linux:

# Copy environment template
cp .env.example .env

# Edit configuration (optional)
nano .env

3. Start the MCP server:

# Start the MCP server (no local ActivityPub server needed)
npm run mcp

Testing the Setup

Test MCP server with MCP Inspector:

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

# Connect to the MCP server
mcp-inspector

Claude Desktop Integration

To use this MCP server with Claude Desktop:

1. Locate your Claude Desktop config file:

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

2. Add the server configuration:

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

3. Restart Claude Desktop to load the new server.

📖 Documentation

Quick Reference

For detailed usage instructions, examples, and troubleshooting, see:

• 📚 Usage Guide - Comprehensive usage documentation
• 🧪 Examples - Practical examples and integration patterns
• 🔧 API Reference - Complete API documentation (below)

API Reference

MCP Resources

Resources provide read-only access to fediverse data from any ActivityPub server. All resources return JSON data unless otherwise specified.

Remote Actor Resource

Get information about any actor in the fediverse:

activitypub://remote-actor/{identifier}

Parameters:

• identifier (string): The actor's fediverse handle (e.g., user@mastodon.social)

Example Response:

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "id": "https://mastodon.social/users/alice",
  "type": "Person",
  "preferredUsername": "alice",
  "name": "Alice Smith",
  "summary": "Software developer passionate about decentralized social networks",
  "inbox": "https://mastodon.social/users/alice/inbox",
  "outbox": "https://mastodon.social/users/alice/outbox"
}

Remote Timeline Resource

Access any actor's timeline/outbox from across the fediverse:

activitypub://remote-timeline/{identifier}

Parameters:

• identifier (string): The actor's fediverse handle (e.g., user@mastodon.social)

Example Response:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollection",
  "id": "https://mastodon.social/users/alice/outbox",
  "totalItems": 42,
  "orderedItems": [...]
}

Instance Info Resource

Get information about any fediverse instance:

activitypub://instance-info/{domain}

Parameters:

• domain (string): The instance domain (e.g., mastodon.social)

Example Response:

{
  "domain": "mastodon.social",
  "software": "mastodon",
  "version": "4.2.1",
  "description": "The original server operated by the Mastodon gGmbH non-profit",
  "registrations": true,
  "stats": {
    "user_count": 900000,
    "status_count": 50000000
  }
}

Remote Followers/Following Resources

Access follower and following lists from any actor:

activitypub://remote-followers/{identifier}
activitypub://remote-following/{identifier}

MCP Tools

Tools enable LLMs to discover and interact with the fediverse. All tools return structured responses with success/error information.

Discover Actor

Discover and get information about any actor in the fediverse:

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

Parameters:

• identifier (string, required): Fediverse handle (e.g., user@mastodon.social)

Fetch Timeline

Fetch recent posts from any actor's timeline:

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

Parameters:

• identifier (string, required): Fediverse handle
• limit (number, optional): Number of posts to fetch (1-50, default: 20)

Get Instance Info

Get detailed information about any fediverse instance:

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

Parameters:

• domain (string, required): Instance domain

Search Instance

Search for content on a specific fediverse instance:

{
  "name": "search-instance",
  "arguments": {
    "domain": "mastodon.social",
    "query": "typescript",
    "type": "accounts"
  }
}

Parameters:

• domain (string, required): Instance domain to search
• query (string, required): Search query
• type (string, optional): Type of content ("accounts", "statuses", "hashtags")

Discover Instances

Find popular fediverse instances by category or topic:

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

Parameters:

• category (string, optional): Software type ("mastodon", "pleroma", "misskey", etc.)
• topic (string, optional): Topic or interest to search for
• size (string, optional): Instance size ("small", "medium", "large")
• region (string, optional): Geographic region or language
• beginnerFriendly (boolean, optional): Show only beginner-friendly instances

Recommend Instances

Get personalized instance recommendations based on interests:

{
  "name": "recommend-instances",
  "arguments": {
    "interests": ["technology", "programming", "open source"]
  }
}

Parameters:

• interests (array, required): List of your interests or topics

MCP Prompts

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

🏗️ Architecture

Project Structure

activitypub-mcp/
├── src/                     # Source code
│   ├── mcp-main.ts          # MCP server entry point
│   ├── mcp-server.ts        # MCP server implementation
│   ├── webfinger.ts         # WebFinger discovery client
│   ├── remote-client.ts     # Remote ActivityPub client
│   ├── instance-discovery.ts # Instance discovery service
│   ├── health-check.ts      # Health monitoring
│   ├── performance-monitor.ts # Performance tracking
│   ├── config.ts            # Configuration constants
│   └── logging.ts           # Logging configuration
├── docs/                    # Documentation
│   ├── setup/               # Installation & configuration guides
│   ├── guides/              # User guides & examples
│   ├── development/         # Development documentation
│   └── specifications/      # Protocol specifications
├── scripts/                 # Installation & setup scripts
├── tests/                   # Test files
├── dist/                    # Built JavaScript files
├── package.json             # Dependencies and scripts
└── README.md               # This file

Technology Stack

• WebFinger: Actor discovery across the fediverse
• MCP SDK: Model Context Protocol implementation
• ActivityPub: Decentralized social networking protocol
• LogTape: Structured logging
• TypeScript: Type-safe development

Communication Flow

LLM Client ←→ MCP Protocol ←→ Fediverse Client ←→ Remote ActivityPub Servers
                                     ↓
                              WebFinger Discovery
                                     ↓
                              Remote Data Fetching

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Setup & Installation - Configuration and installation guides
• User Guides - Usage examples and tutorials
• Development - Development setup and best practices
• Specifications - ActivityPub and protocol specifications

See the Documentation Index for a complete overview.

🔧 Development

Available Scripts

• npm run mcp - Start MCP server
• npm run mcp:dev - Start MCP server in watch mode
• npm run test - Run tests
• npm run build - Build TypeScript

Environment Variables

Create a .env file:

# MCP Server configuration
MCP_SERVER_NAME=activitypub-mcp
MCP_SERVER_VERSION=1.0.0

# Rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=900000

# Logging
LOG_LEVEL=info

Testing

# Test MCP server with inspector
mcp-inspector

# Test fediverse interactions
npm run test

# Manual testing with specific actors
# Use the discover-actor tool to test WebFinger discovery

🌐 Cross-Platform Compatibility

This project is designed to work seamlessly across different operating systems:

Supported Platforms

• Windows 10/11 (PowerShell, Command Prompt, Git Bash)
• macOS (Bash, Zsh)
• Linux (Bash, most distributions)

Platform-Specific Features

• Automatic script detection: npm scripts automatically choose the right script for your platform
• Native path handling: Proper configuration paths for each platform
• Shell compatibility: Both PowerShell (.ps1) and Bash (.sh) scripts provided

Installation Methods by Platform

Troubleshooting Platform Issues

Windows PowerShell Execution Policy:

# If you get execution policy errors, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Git Bash:

# Git Bash users can use Unix-style commands:
npm run setup:unix

Linux/macOS Permissions:

# If you get permission errors, make scripts executable:
chmod +x scripts/*.sh

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Fedify - ActivityPub server framework
• Model Context Protocol - LLM integration standard
• ActivityPub - W3C decentralized social networking protocol

🔗 Links

• ActivityPub Specification
• Model Context Protocol
• Fedify Documentation
• Fediverse

Made with ❤️ for the decentralized web and AI integration