io.github.cameronrye/activitypub-mcp
Read-only-by-default MCP server: let LLMs explore the Fediverse — Mastodon, Misskey, Pleroma.
Open source Open in the app JSON README (API)
About
Read-only-by-default MCP server: let LLMs explore the Fediverse — Mastodon, Misskey, Pleroma.
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- cameronrye
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.2.1
- Stars
- 17
- Forks
- 5
- Open pull requests
- 23
- Last push
- 2026-09-07T10:08:15Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:33
- Updated
- 2026-08-29 03:02:33
- Origin id
io.github.cameronrye/activitypub-mcp
README
<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:**
[](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-<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/).