ActivityPub MCP Server

Fediverse Client for LLMs

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.

What's New in v1.1.0

The biggest release yet! Now with full write capabilities, multi-account support, and enterprise-ready features.

Post & Interact Create posts, reply, boost, favourite, and bookmark directly from your LLM	Multi-Account Manage multiple fediverse accounts with secure credential storage	Media & Polls Upload images with alt text, vote on polls, schedule posts
Export Anywhere Export timelines, threads, and accounts to JSON, Markdown, or CSV	HTTP Transport Production-ready HTTP/SSE mode for enterprise deployments	53 Tools 21 read-only + 28 authenticated + 4 export tools

See Authenticated Tools | See Export Tools | Full Changelog

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
Dual Transport: Supports both stdio (Claude Desktop) and HTTP transport modes

Fediverse Interaction Features

Remote Actor Discovery: Find users on any fediverse instance
Timeline Fetching: Get posts from any user's timeline with pagination support
Trending Content: Access trending hashtags and posts
Instance Discovery: Find and explore fediverse instances via live API
Instance Information: Get detailed info about any server
Search Capabilities: Search for accounts, hashtags, and posts across instances
Post Threads: Fetch complete conversation threads with replies
WebFinger Support: Resolve actor identifiers across the network
Multi-Platform Support: Works with Mastodon, Pleroma, Misskey, and more
Follower/Following Lists: Access social connections
Batch Operations: Fetch multiple actors or posts in a single request

MCP Features

Resources (10 total): Access remote ActivityPub data (actors, timelines, trending, instance info)
Tools (53 total): Discover, interact, and create content in the fediverse
- 21 read-only tools for discovery and exploration (including unified search)
- 28 authenticated tools for posting, interactions, polls, media, and scheduling
- 4 export tools for data export in JSON, Markdown, or CSV formats
Prompts (11 total): Templates for fediverse exploration, content strategy, and community analysis
Monitoring: Built-in logging, audit trails, and performance metrics
Health Checks: Server health monitoring and diagnostics

Authenticated Features (v1.1.0)

Multi-Account Support: Manage multiple fediverse accounts with secure credential storage
Posting Operations: Create, reply to, and delete posts
Social Interactions: Boost, favourite, bookmark, follow, mute, and block
Authenticated Timelines: Access home timeline, notifications, bookmarks, and favourites
Content Export: Export timelines, threads, and account data in multiple formats

Security & Administration

Instance Blocklist: Block specific instances by domain or wildcard pattern
Audit Logging: Comprehensive logging of all tool invocations and resource access
Content Warnings: Respect and display content warnings from posts
Rate Limiting: Protect against abuse with configurable rate limits

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

Clone and install dependencies:

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

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

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:

Locate your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the server configuration:

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

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.

Server Info Resource

Get information about the ActivityPub MCP server:

activitypub://server-info

Parameters:

None required

Example Response:

{
  "name": "activitypub-mcp",
  "version": "1.1.0",
  "description": "A Model Context Protocol server for exploring and interacting with the existing Fediverse",
  "capabilities": {
    "resources": ["server-info", "remote-actor", "remote-timeline", "remote-followers", "remote-following", "instance-info", "trending", "local-timeline", "federated-timeline", "post-thread"],
    "tools": {
      "discovery": ["discover-actor", "discover-instances", "discover-instances-live", "recommend-instances"],
      "content": ["fetch-timeline", "get-post-thread", "search-instance", "search-accounts", "search-hashtags", "search-posts"],
      "timelines": ["get-trending-hashtags", "get-trending-posts", "get-local-timeline", "get-federated-timeline"],
      "utility": ["convert-url", "batch-fetch-actors", "batch-fetch-posts"],
      "system": ["health-check", "performance-metrics"]
    },
    "prompts": ["explore-fediverse", "discover-content", "compare-instances", "compare-accounts", "analyze-user-activity", "find-experts", "summarize-trending"]
  },
  "features": {
    "auditLogging": true,
    "instanceBlocklist": true,
    "contentWarnings": true,
    "batchOperations": true
  }
}

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}

Trending Resource (New)

Get trending hashtags and posts from an instance:

activitypub://trending/{domain}

Local Timeline Resource (New)

Get the local public timeline from an instance:

activitypub://local-timeline/{domain}

Federated Timeline Resource (New)

Get the federated public timeline from an instance:

activitypub://federated-timeline/{domain}

Post Thread Resource (New)

Get a post and its full conversation thread:

activitypub://post-thread/{postUrl}

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 posts from any actor's timeline with pagination support:

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

Parameters:

identifier (string, required): Fediverse handle
limit (number, optional): Number of posts to fetch (1-50, default: 20)
cursor (string, optional): Pagination cursor from previous response
minId (string, optional): Return results newer than this ID
maxId (string, optional): Return results older than this ID
sinceId (string, optional): Return results since this ID

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": {
    "i

ActivityPub MCP Server

ActivityPub MCP Server

What's New in v1.1.0

Features

Core Capabilities

Fediverse Interaction Features

MCP Features

Authenticated Features (v1.1.0)

Security & Administration

Quick Start

Prerequisites

Cross-Platform Support

One-Click Installation

Universal (All Platforms)

Platform-Specific Installation

Manual Installation

Testing the Setup

Claude Desktop Integration

Documentation

Quick Reference

API Reference

MCP Resources

Server Info Resource

Remote Actor Resource

Remote Timeline Resource

Instance Info Resource

Remote Followers/Following Resources

Trending Resource (New)

Local Timeline Resource (New)

Federated Timeline Resource (New)

Post Thread Resource (New)

MCP Tools

Discover Actor

Fetch Timeline

Get Instance Info

Search Instance

Discover Instances

Recommend Instances

Comments (0)