# ActivityPub MCP Server

> 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.

## Overview

The ActivityPub MCP Server is a Fediverse client that allows AI assistants to discover actors, fetch timelines, explore instances, and search content across the decentralized social web. It implements the complete MCP specification with resources for data access, tools for interaction, and prompts for guided exploration.

### Key Features

- **Read-only by default**: discovery and timeline tools work with no credentials; all write/mutation tools are opt-in behind `ACTIVITYPUB_ENABLE_WRITES`
- **Fediverse Integration**: Mastodon, Pleroma, Misskey, Foundkey, and compatible ActivityPub servers; Misskey-family reads are routed per instance by NodeInfo software detection
- **WebFinger Discovery**: Find and resolve actors across the network
- **37 MCP Tools**: 9 read-only discovery/timeline + 28 authenticated (post, follow, boost, polls, media, schedule)
- **10 MCP Resources, 5 MCP Prompts**: Including dynamic `server-info` from the live capability registry
- **Multi-Account Support**: `activitypub-mcp login` (Mastodon OAuth2 / Misskey MiAuth) or pipe-delimited `ACTIVITYPUB_ACCOUNTS`; per-call account selection
- **Dual Transport**: stdio (Claude Desktop / Cursor) and HTTP (Bearer-authenticated `/mcp`)
- **TypeScript Implementation**: Modern, type-safe codebase with strict TS and ESM
- **Cross-Platform Support**: Works on Windows, macOS, and Linux (Node 20+)
- **Security-Hardened**: SSRF guard on all outbound calls, streaming response-size caps, instance blocklist, thread cross-origin gating, audit logging on every write tool

## Quick Start

Requires **Node.js 20+** (Node 18 reached EOL April 2025).

```bash
# Install via npm
npm install -g activitypub-mcp

# Or use with npx
npx activitypub-mcp

# Verify installation
activitypub-mcp --version
```

### Claude Desktop Integration

Add to your Claude Desktop configuration:

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

## Documentation

### Getting Started

- [Installation & Setup](https://cameronrye.github.io/activitypub-mcp/docs/getting-started/installation/): Complete setup instructions
- [Claude Desktop Integration](https://cameronrye.github.io/activitypub-mcp/docs/getting-started/claude-desktop/): Configure with Claude Desktop
- [Configuration](https://cameronrye.github.io/activitypub-mcp/docs/getting-started/configuration/): Environment variables and options
- [Cross-Platform Setup](https://cameronrye.github.io/activitypub-mcp/docs/getting-started/cross-platform/): Platform-specific installation

## API Reference

- [MCP Tools](https://cameronrye.github.io/activitypub-mcp/docs/api/tools/): Interactive tools for fediverse discovery and content fetching
- [MCP Resources](https://cameronrye.github.io/activitypub-mcp/docs/api/resources/): Read-only access to remote ActivityPub data
- [MCP Prompts](https://cameronrye.github.io/activitypub-mcp/docs/api/prompts/): Templates for fediverse exploration and discovery

## Guides & Examples

- [Basic Usage](https://cameronrye.github.io/activitypub-mcp/docs/guides/basic-usage/): Getting started with the MCP server
- [Examples](https://cameronrye.github.io/activitypub-mcp/docs/guides/examples/): Practical examples and integration patterns
- [Fediverse Exploration](https://cameronrye.github.io/activitypub-mcp/docs/guides/fediverse-exploration/): Discover actors, instances, and content
- [Advanced Workflows](https://cameronrye.github.io/activitypub-mcp/docs/guides/advanced-workflows/): Best practices and real-world scenarios

## Development

- [Architecture](https://cameronrye.github.io/activitypub-mcp/docs/development/architecture/): System design and internals
- [Dependency Management](https://cameronrye.github.io/activitypub-mcp/docs/development/dependencies/): Managing project dependencies
- [Performance Monitoring](https://cameronrye.github.io/activitypub-mcp/docs/development/performance/): Built-in logging and metrics
- [Security Audit](https://cameronrye.github.io/activitypub-mcp/docs/development/security/): Security best practices and audit checklist

## Specifications

- [ActivityPub Guide](https://cameronrye.github.io/activitypub-mcp/docs/specifications/activitypub/): Understanding ActivityPub for LLM integration
- [WebFinger Guide](https://cameronrye.github.io/activitypub-mcp/docs/specifications/webfinger/): Actor discovery via WebFinger
- [ActivityStreams Guide](https://cameronrye.github.io/activitypub-mcp/docs/specifications/activitystreams/): The ActivityStreams vocabulary

## Project Resources

- [GitHub Repository](https://github.com/cameronrye/activitypub-mcp): Source code and issue tracking
- [npm Package](https://www.npmjs.com/package/activitypub-mcp): Install via npm
- [Documentation Site](https://cameronrye.github.io/activitypub-mcp/): Complete documentation
- [Changelog](https://cameronrye.github.io/activitypub-mcp/docs/reference/changelog/): Version history and updates

## Additional Resources

### Troubleshooting & Support

- [Troubleshooting Guide](https://cameronrye.github.io/activitypub-mcp/docs/reference/troubleshooting/): Common issues and solutions
- [GitHub Issues](https://github.com/cameronrye/activitypub-mcp/issues): Report bugs, request features, and ask for help

### External Documentation

- [ActivityPub Specification](https://www.w3.org/TR/activitypub/): W3C ActivityPub protocol specification
- [Model Context Protocol](https://modelcontextprotocol.io/): MCP specification and documentation
- [Fedify Documentation](https://fedify.dev/): ActivityPub server framework
- [Fediverse Info](https://fediverse.info/): General information about the Fediverse

### Complete Documentation

For comprehensive documentation including detailed API reference, examples, troubleshooting, and specifications, see:
- [llms-full.txt](https://cameronrye.github.io/activitypub-mcp/llms-full.txt): Complete documentation for LLMs

### v2 Migration

Upgrading from v1.x? See [MIGRATION-v2.md](https://github.com/cameronrye/activitypub-mcp/blob/main/MIGRATION-v2.md) for the breaking-change checklist: Node 20+, required `MCP_HTTP_SECRET` for HTTP transport, empty CORS default, pipe-delimited `ACTIVITYPUB_ACCOUNTS`, `HEALTH_CHECK_EXTERNAL_PROBE` in place of removed `HEALTH_CHECK_ENABLED`, `scheduledId` → `scheduledPostId`, and `get-relationship` taking single `acct` (not `accountIds[]`).

---

**Version:** 3.1.4
**License:** MIT
**Maintainer:** Cameron Rye (https://rye.dev/)
**Repository:** https://github.com/cameronrye/activitypub-mcp
