activitypub-mcp

<p align="center">
  <img src="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="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](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/](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](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](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/).