Overview
The ActivityPub MCP Server is a comprehensive implementation of the Model Context Protocol that enables LLMs to explore and interact with the existing Fediverse. Unlike traditional ActivityPub servers that host content, this is a Fediverse client designed specifically for AI consumption, allowing LLMs to discover actors, fetch timelines, and explore instances across the decentralized social web.
The Fediverse Connection
The Fediverse is a collection of federated social networks including Mastodon, Pleroma, Misskey, and many others, all communicating via the ActivityPub protocol. This MCP server acts as a bridge, enabling AI assistants to navigate this decentralized ecosystem through natural language.
Architecture
LLM Client ←→ MCP Protocol ←→ Fediverse Client ←→ Remote ActivityPub Servers
↓
WebFinger Discovery
↓
Remote Data Fetching
Key Design Principles
- Client-Only: No server hosting—purely a client for exploring existing Fediverse content
- WebFinger Discovery: Find actors across any fediverse instance
- Multi-Platform: Works with Mastodon, Pleroma, Misskey, and more
- LLM-Optimized: Structured responses designed for AI consumption
Features
🌐 Fediverse Interaction
- 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
- Follower/Following Lists: Access social connections
🔧 MCP Implementation
- 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 & Performance
- Built-in Logging: Structured logging with LogTape
- Performance Metrics: Track response times and success rates
- Health Monitoring: Server status and diagnostics
- Rate Limiting: Respect instance rate limits
Available Tools
Discovery Tools
- discover-actor: Find and get information about any actor in the fediverse
- fetch-timeline: Get recent posts from any user’s timeline
- discover-instances: Find popular fediverse instances by category or topic
- recommend-instances: Get personalized instance recommendations
Instance Tools
- get-instance-info: Get detailed information about any fediverse instance
- search-instance: Search for content on a specific instance
MCP Resources
- activitypub://remote-actor/{identifier}: Get actor information
- activitypub://remote-timeline/{identifier}: Access actor timelines
- activitypub://instance-info/{domain}: Get instance details
- activitypub://remote-followers/{identifier}: View follower lists
- activitypub://remote-following/{identifier}: View following lists
Technical Implementation
Built With Modern Standards
- TypeScript: Full type safety with modern ESM
- Fedify: ActivityPub server framework
- MCP SDK: Model Context Protocol implementation
- LogTape: Structured logging
- WebFinger: Actor discovery across the network
Cross-Platform Support
Works seamlessly on:
- Windows (PowerShell, Command Prompt, Git Bash)
- macOS (Bash, Zsh)
- Linux (Bash, most distributions)
Getting Started
One-Click Installation
# 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
Claude Desktop Integration
Add to your Claude Desktop configuration:
{
"mcpServers": {
"activitypub": {
"command": "npx",
"args": ["-y", "activitypub-mcp"]
}
}
}
Example Interactions
Once configured, you can ask Claude:
- “Find information about @[email protected]”
- “Show me the latest posts from @[email protected]”
- “What instances are good for technology discussions?”
- “Search for posts about AI on mastodon.social”
- “Recommend fediverse instances for open source developers”
Use Cases
For Users
- Fediverse Exploration: Discover new instances and users
- Content Discovery: Find interesting posts and discussions
- Instance Research: Compare different fediverse servers
- Network Analysis: Understand fediverse connections
For Developers
- ActivityPub Learning: Understand the protocol through AI interaction
- Instance Discovery: Find the right server for your needs
- Content Aggregation: Build tools that explore the fediverse
- Research Tools: Analyze decentralized social networks
Development
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
Configuration
Environment variables for customization:
# 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
Documentation
Comprehensive documentation available:
- Setup & Installation: Configuration and installation guides
- User Guides: Usage examples and tutorials
- Development: Development setup and best practices
- Specifications: ActivityPub and protocol specifications
Community Impact
This project enables:
- AI-Powered Fediverse Exploration: Natural language interaction with decentralized social networks
- Lower Barriers: Make the Fediverse more accessible through AI assistance
- Protocol Education: Learn ActivityPub through practical AI interaction
- Open Ecosystem: Contribute to both MCP and Fediverse communities
Future Roadmap
- Enhanced search capabilities
- Support for more ActivityPub implementations
- Advanced filtering and discovery
- Content caching for performance
- Multi-instance aggregation
Acknowledgments
- Fedify: ActivityPub server framework
- Model Context Protocol: LLM integration standard
- ActivityPub: W3C decentralized social networking protocol
- Fediverse Community: The vibrant decentralized social web
Status: Production Ready
License: MIT
Maintained: Active Development