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+**.
```bash
npx -y activitypub-mcp
```
**One-click install:**
[](https://cursor.com/install-mcp?name=activitypub-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFjdGl2aXR5cHViLW1jcCJdfQ==)
[](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-.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 `` 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/).