activitypub-mcp

ActivityPub MCP Server

Fediverse Client for LLMs

A lightweight Model Context Protocol (MCP) 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.

-->

Install

Requires Node.js 20+.

npx -y activitypub-mcp

One-click install:

Claude Desktop

One-click: download the `.mcpb` bundle (`activitypub-mcp-.mcpb`) from the latest release 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):

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

Restart Claude Desktop.

Cursor

Edit `~/.cursor/mcp.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 before enabling.**

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

Authentication

Log in with the CLI:

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/** 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):

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 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 `` envelope and read-only default reduce the risk surface, but do not eliminate it.

See 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/**

License

MIT — see LICENSE.

Acknowledgments

Built on the Model Context Protocol by Anthropic, and interacts with the decentralized social web as specified by ActivityPub (W3C) and ActivityStreams.