# cameronrye/activitypub-mcp [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/cameronrye/activitypub-mcp  
**GitHub Stars:** 17  
**npm Downloads (last month):** 521  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cameronrye-activitypub-mcp

## Description
A comprehensive MCP server that enables LLMs to explore and interact with the Fediverse through ActivityPub protocol. Features WebFinger discovery, timeline fetching, instance exploration, and cross-platform support for Mastodon, Pleroma, Misskey, and other ActivityPub servers.

## Tools
Capabilities this server exposes over MCP:

- **discover-actor** — Find and retrieve the profile of any fediverse user or account (called an 'actor' in ActivityPub). Returns display name, bio, follower/following URLs, and inbox/outbox endpoints. Pass a handle like '@alice@mastodon.social' or 'alice@mastodon.social'.
- **discover-instances** — Discover fediverse instances in real-time using the instances.social API with advanced filtering
- **fetch-timeline** — Fetch recent posts (the outbox) from any fediverse actor — a user or account — with cursor- and ID-based pagination. Pass a handle like 'alice@mastodon.social'.
- **get-post-thread** — Fetch a post and its full conversation thread including replies and parent posts
- **search** — Unified search across the fediverse - find accounts, posts, or hashtags on any instance
- **get-trending-hashtags** — Get currently trending hashtags on a fediverse instance (Mastodon-compatible instances that expose a trends API).
- **get-trending-posts** — Get currently trending posts on a fediverse instance (Mastodon-compatible instances that expose a trends API).
- **get-public-timeline** — Fetch an instance's public timeline. scope 'federated' (default) shows posts the instance has seen from across the fediverse; 'local' shows only posts authored on that instance.
- **get-instance-info** — Get detailed information about a fediverse instance: software and version, description, registration policy, supported languages, user/post/domain counts, and contact account.
- **list-accounts** — List all configured authenticated accounts for write operations
- **switch-account** — Switch the active account used for write operations
- **verify-account** — Verify that the account credentials are valid and get account information
- **get-home-timeline** — Get your personalized home timeline (posts from accounts you follow)
- **get-notifications** — Get your notifications (mentions, follows, boosts, favourites)
- **get-bookmarks** — Get your bookmarked posts
- **get-favourites** — Get posts you have favourited
- **get-relationship** — Check your relationship status with another account (following, followed by, blocking, muting, etc.). Pass a single acct like 'username@instance'. To check multiple accounts, call this tool once per account.
- **get-scheduled-posts** — List your scheduled posts that haven't been published yet

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `ACTIVITYPUB_ENABLE_WRITES`, `ACTIVITYPUB_DEFAULT_INSTANCE`, `ACTIVITYPUB_DEFAULT_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

<p align="center">
  <img src="https://raw.githubusercontent.com/cameronrye/activitypub-mcp/HEAD/public/logo.svg" alt="ActivityPub MCP Logo" width="200" />
</p>

<h1 align="center">ActivityPub MCP Server</h1>

<p align="center">
  <strong>Fediverse Client for LLMs</strong>
</p>

<p align="center">
  A lightweight <strong>Model Context Protocol (MCP)</strong> server that lets an LLM explore and interact with the existing Fediverse — Mastodon, Misskey, Foundkey, Pleroma, and compatible servers. Read-only by default; write tools are opt-in.
</p>

<!--
  DEMO: record a ~20-30s screen capture of a Claude session using activitypub-mcp
  (see docs/launch-kit.md for the shot list), save it to docs/demo.gif, then
  uncomment the block below. Kept commented so the README never shows a broken image.

<p align="center">
  <img src="https://raw.githubusercontent.com/cameronrye/activitypub-mcp/HEAD/docs/demo.gif" alt="Demo: Claude exploring the Fediverse via activitypub-mcp" width="720" />
</p>
-->

<p align="center">
  <a href="https://badge.fury.io/js/activitypub-mcp"><img src="https://badge.fury.io/js/activitypub-mcp.svg" alt="npm version" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript" /></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-20+-339933?logo=node.js&logoColor=white" alt="Node.js" /></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-blueviolet" alt="MCP Compatible" /></a>
</p>

<p align="center">
  <a href="https://github.com/cameronrye/activitypub-mcp/actions"><img src="https://github.com/cameronrye/activitypub-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://www.npmjs.com/package/activitypub-mcp"><img src="https://img.shields.io/npm/dm/activitypub-mcp.svg" alt="npm downloads" /></a>
  <a href="https://github.com/cameronrye/activitypub-mcp"><img src="https://img.shields.io/github/stars/cameronrye/activitypub-mcp?style=social" alt="GitHub stars" /></a>
</p>

<p align="center">
  <a href="https://glama.ai/mcp/servers/cameronrye/activitypub-mcp"><img src="https://glama.ai/mcp/servers/cameronrye/activitypub-mcp/badge" alt="Glama quality and maintenance score" width="200" /></a>
  <a href="https://smithery.ai/servers/rye/activitypub-mcp"><img src="https://smithery.ai/badge/rye/activitypub-mcp" alt="Smithery" /></a>
</p>

---

## Install

Requires **Node.js 20+**.

```bash
npx -y activitypub-mcp
```

**One-click install:**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=activitypub-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFjdGl2aXR5cHViLW1jcCJdfQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=activitypub-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22activitypub-mcp%22%5D%7D)

### Claude Desktop

**One-click:** download the `.mcpb` bundle (`activitypub-mcp-<version>.mcpb`) from the [latest release](https://github.com/cameronrye/activitypub-mcp/releases/latest) and open it in Claude Desktop.

**Manual:** edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

Restart Claude Desktop.

### Cursor

Edit `~/.cursor/mcp.json`:

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

Restart Cursor.

---

## Read-only by default

Out of the box, only **read tools** are registered: discover actors, fetch timelines, search, get threads, explore instances, read trending content. No write tools exist in the MCP session, so injected fediverse content cannot trigger account actions.

**Public read tools** (no account needed): `discover-actor`, `fetch-timeline`, `get-post-thread`, `get-instance-info`, `get-public-timeline`, `get-trending-hashtags`, `get-trending-posts`, `search`, `discover-instances`.

**Authenticated read tools** (account required): `list-accounts`, `switch-account`, `verify-account`, `get-home-timeline`, `get-notifications`, `get-bookmarks`, `get-favourites`, `get-relationship`.

### Enabling writes

Set `ACTIVITYPUB_ENABLE_WRITES=true` in the environment or MCP config `env` block. This registers the full set of mutation tools: post, reply, delete, boost, favourite, bookmark, follow, mute, block, vote, upload media, and scheduled posts. **Read the [threat model](https://github.com/cameronrye/activitypub-mcp/blob/HEAD/SECURITY.md) before enabling.**

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

### Authentication

Log in with the CLI:

```bash
npx activitypub-mcp login mastodon.social
```

This runs OAuth (Mastodon-family) or MiAuth (Misskey) in your browser and saves credentials to `~/.config/activitypub-mcp/accounts.json`. Multi-account is supported — use `switch-account` to change the active account.

Alternatively, set `ACTIVITYPUB_DEFAULT_INSTANCE` and `ACTIVITYPUB_DEFAULT_TOKEN` env vars for a single account without the CLI flow.

---

## Platform support

`discover-actor` and `fetch-timeline` speak plain ActivityPub (WebFinger → actor → outbox), so they read **any** conformant ActivityPub server — Mastodon, Misskey, Foundkey, Pleroma/Akkoma, **Lemmy** (communities and users), **PeerTube** (channels and accounts), **GoToSocial**, and **Pixelfed**.

The instance-API read tools (`search`, `get-trending-hashtags`, `get-trending-posts`, `get-public-timeline`) and every write tool require a **Mastodon- or Misskey-API** instance, since they call those platforms' REST APIs. Login uses OAuth (Mastodon-family) or MiAuth (Misskey).

---

## Example

After adding the server to your MCP client, try:

> "Look up @gargron@mastodon.social and summarize their latest posts."

The model will call `discover-actor` to fetch the profile, then `fetch-timeline` to read recent posts.

See **[examples/](https://github.com/cameronrye/activitypub-mcp/blob/HEAD/examples/)** for copy-pasteable recipes — Fediverse research digests, scheduled threads, notification triage, image posts with alt text, and topic curation.

---

## HTTP transport

In addition to stdio (default), the server supports HTTP mode with a bearer-gated `/mcp` endpoint and `/health` liveness check. Set `MCP_HTTP_SECRET` (min 16 chars) to enable.

To self-host it as a service, the repo includes a `Dockerfile` and a `docker-compose.yml` (HTTP mode):

```bash
export MCP_HTTP_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
docker compose up --build   # then: curl http://localhost:8080/health
```

See the [docs](https://cameronrye.github.io/activitypub-mcp/docs/getting-started/configuration/) for full configuration.

---

## Security

This server fetches world-writable fediverse content — posts, bios, notifications — and feeds it to the LLM. That content can contain prompt-injection payloads. Notifications are an unsolicited channel: anyone can mention your account. The `<untrusted-content>` envelope and read-only default reduce the risk surface, but **do not eliminate it**.

See [SECURITY.md](https://github.com/cameronrye/activitypub-mcp/blob/HEAD/SECURITY.md) for the full threat model, SSRF protections, credential handling, and reporting instructions.

---

## Documentation

The full tool reference, resource list, prompt catalog, environment variable guide, and deployment notes live on the docs site:

**[cameronrye.github.io/activitypub-mcp/docs/](https://cameronrye.github.io/activitypub-mcp/docs/)**

---

## License

MIT — see [LICENSE](https://github.com/cameronrye/activitypub-mcp/blob/HEAD/LICENSE).

## Acknowledgments

Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic, and interacts with the decentralized social web as specified by [ActivityPub](https://www.w3.org/TR/activitypub/) (W3C) and [ActivityStreams](https://www.w3.org/TR/activitystreams-core/).