Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Mastodon

FreeNot checked

A Mastodon client MCP server providing full webapp and agent automation for the Fediverse, with human-approved outbox for promotion drafts and comprehensive MCP

GitHubEmbed

About

A Mastodon client MCP server providing full webapp and agent automation for the Fediverse, with human-approved outbox for promotion drafts and comprehensive MCP tools for timeline, posting, and account management.

README

Just Python FastMCP CI ActivityPub MIT

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)

from github.com/sandraschi/mastodon-mcp

Installing Mastodon

This server has no published package — it is built from source. Open the repository and follow its README.

▸ github.com/sandraschi/mastodon-mcp

FAQ

Is Mastodon MCP free?

Yes, Mastodon MCP is free — one-click install via Unyly at no cost.

Does Mastodon need an API key?

No, Mastodon runs without API keys or environment variables.

Is Mastodon hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Mastodon in Claude Desktop, Claude Code or Cursor?

Open Mastodon on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Compare Mastodon with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All ai MCPs