mastodon-mcp

<p align="center"> <a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a> <a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.4%2B-7c5cfc?style=flat-square" alt="FastMCP"></a> <a href="https://github.com/sandraschi/mastodon-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/sandraschi/mastodon-mcp/ci.yml?branch=master&style=flat-square" alt="CI"></a> <a href="https://joinmastodon.org/"><img src="https://img.shields.io/badge/Fediverse-ActivityPub-6364FF?style=flat-square" alt="ActivityPub"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="MIT"></a> </p>

Fediverse Mastodon client (ActivityPub) — full webapp + MCP agent automation, including a human-approved outbox for promotion drafts from fleet-public-relations-mcp.

v0.1.1 · Ports 10754 / 10755 · Sibling of discord-mcp · AT Proto sibling bluesky-mcp

FastMCP 3.4+ · full portmanteau (reply/boost/media/webhooks) · SOTA webapp · dry-run default · Windows CI + local just ci

Mastodon = ActivityPub. Not Bluesky. Primer: docs/FEDIVERSE.md.

---

Principle

Agents draft and assist. Humans approve fleet promotion posts. Interactive client use still respects dry-run until you go live.

Tone: FLEET_PROMOTION.md.

---

Features

• Full Mastodon web client: Inbox, Timelines, Compose (AI assist), Chat, Accounts, Skills, Tools, Settings, Help
• Agent automation via mastodon_social portmanteau + Prefab cards
• Human-approved outbox + fleet-PR REST handoff (safety gate — not the only job)
• Dry-run default; inbound webhooks with shared secret
• Ruff + Biome + pytest gate; Windows-only CI workflow

---

Quick start

cd D:\Dev\repos\mastodon-mcp
Copy-Item .env.example .env
# Edit MASTODON_INSTANCE + MASTODON_ACCESS_TOKEN
.\start.bat

Dashboard: http://127.0.0.1:10755 · MCP: http://127.0.0.1:10754/mcp

---

Documentation

Doc	Contents
INSTALL.md	Install paths
docs/ONBOARDING.md	First-timer: account, money/CC, pitfalls, sanity check
docs/CONFIGURATION.md	Env vars
docs/TOOLS.md	MCP + REST reference
docs/DEVELOPMENT.md	Lint, just ci, packaging
docs/TROUBLESHOOTING.md	Symptom → fix

---

Ports

Service	Port
Backend	10754
Webapp	10755

---

MCP tools

Portmanteau mastodon_social — all operations implemented (see docs/TOOLS.md). Also mastodon_help, mastodon_shutdown, show_outbox_card.

---

Quality

just ci

Private repos: GitHub Actions stay disabled at account level (billing). Workflow file is still required; run just ci locally.

---

License

MIT (see LICENSE if present)