Post to Mastodon via MCP

Quick navigation: Which path should I use? · Multi-platform example · Recovery playbook · All 9 platforms at a glance

Prerequisites: VoxBurst MCP server configured. See MCP Server setup.

Mastodon is decentralized. Each account specifies its instance (e.g., mastodon.social, fosstodon.org). Character limits, media limits, and content policies vary by instance. The default is 500 characters, but some instances allow up to 5,000.

The complete flow

Find the Mastodon account ID


list_accounts()

Look for "platform": "mastodon". The displayName or username will show the full handle including the instance (e.g., @mybrand@mastodon.social).

Optionally validate content first


validate_content(
  content: "Your toot text here",
  platforms: ["MASTODON"]
)

VoxBurst validates against the default 500-character limit. If your instance allows more, the validation is conservative — the actual post may succeed even if validation warns.

Create the post

See post type examples below.

Check the result


get_post(postId: "post_abc123")


{
  "id": "post_abc123",
  "status": "published",
  "platforms": [
    {
      "platform": "mastodon",
      "status": "published",
      "platformPostUrl": "https://mastodon.social/@mybrand/1234567890",
      "publishedAt": "2026-06-01T09:30:02Z",
      "error": null
    }
  ]
}

What type of post do you want?

I want to post…	contentType	Media required?	Notes
Text only	`TEXT`	No	Max 500 chars (default; varies by instance)
Image(s)	`IMAGE`	Yes — 1–4 images	Max 8 MB per image
A video	`VIDEO`	Yes — 1 video	Max 5 min, max 40 MB

Mastodon does not support first comments, carousels, Reels, Stories, or threads via the VoxBurst MCP.

Media input options:

mediaUrls — public HTTPS image/video URLs (auto-registered)
mediaIds — VoxBurst media IDs from prior uploads

Post type examples

Text post (toot)


create_post(
  content: "Just published a new post on decentralized social media strategy. Link below. #Mastodon #Fediverse",
  accountIds: ["acc_mastodon_abc123"],
  contentType: "TEXT"
)

Image post


create_post(
  content: "Open source tools we shipped this month 🛠️ #FOSS #OpenSource",
  accountIds: ["acc_mastodon_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/tools-release.jpg"]
)

Multiple images (up to 4)


create_post(
  content: "Screenshots from the new release →",
  accountIds: ["acc_mastodon_abc123"],
  contentType: "IMAGE",
  mediaUrls: [
    "https://cdn.example.com/screen-1.jpg",
    "https://cdn.example.com/screen-2.jpg",
    "https://cdn.example.com/screen-3.jpg"
  ]
)

Video post


create_post(
  content: "Quick demo of our scheduling tool. No sign-up required.",
  accountIds: ["acc_mastodon_abc123"],
  contentType: "VIDEO",
  mediaUrls: ["https://cdn.example.com/demo.mp4"]
)

Scheduled post


create_post(
  content: "We are speaking at FediverseCon next week. Come say hello. 👋",
  accountIds: ["acc_mastodon_abc123"],
  contentType: "TEXT",
  scheduledFor: "2026-06-02T08:00:00Z"
)

Tell your AI agent this

Text post, post now:

Post to Mastodon account [acc_id]. Content: [your text — max 500 chars]. Post now.

Image, scheduled:

Post to Mastodon account [acc_id]. Content: [text]. Attach image: [https://...]. Schedule for [ISO timestamp].

Validate first:

Validate this Mastodon toot before posting: [text]. Check it is within the 500-character default limit.

Failure cookbook

Error	Cause	Fix
`CONTENT_TOO_LONG`	Over the instance’s character limit	Shorten the text; check your instance’s actual limit (may differ from the default 500)
`INVALID_APP_PASSWORD`	App password revoked or account re-secured	Generate a new app password in your instance’s settings and re-connect in VoxBurst
`OAUTH_TOKEN_INVALID`	Per-instance OAuth credentials changed	Re-connect the Mastodon account; credentials are per-instance
`IMAGE_TOO_LARGE`	Image over 8 MB (default Mastodon limit)	Compress to under 8 MB before uploading
`VIDEO_TOO_LARGE`	Video over 40 MB	Compress or trim
`INSTANCE_UNREACHABLE`	Instance is offline or rate-limiting	Wait and retry; call `retry_post` for transient failures
`MEDIA_NOT_PROCESSED`	Mastodon rejected the media type	Check the instance’s allowed MIME types; re-upload in a supported format
Post status `failed`	Mastodon API error	Read `platforms[].error`; retry transient errors with `retry_post`

Account requirements

Requirement	Detail
Account type	Any Mastodon account on any instance
Auth method	OAuth 2.0 (per-instance credentials)
Key precondition	Instance URL required at connection time (e.g. `mastodon.social`, `fosstodon.org`) — credentials are registered per-instance, not globally
Re-connect trigger	OAuth token revoked or instance changed; re-connect in VoxBurst Settings

When Mastodon is a poor fit

Broad marketing reach — Mastodon instances are small, topic-focused communities; viral reach is limited compared to centralized platforms
Consistent character limits — the default is 500 characters but each instance sets its own limit; a post valid on mastodon.social may fail on a stricter instance
Carousel posts — not supported
First comment CTAs — first comments are not supported; include the CTA in the post body

Cross-platform override example

Mastodon and Bluesky are both text-forward federated platforms but have different cultures and limits. Override each independently:


create_post(
  content: "New release: version 2.0 is out.",
  accountIds: ["acc_mastodon_stu", "acc_bluesky_pqr", "acc_twitter_def"],
  contentType: "TEXT",
  platformOverrides: {
    "MASTODON": {
      "content": "VoxBurst 2.0 is out today. Cross-platform scheduling for the open web. #OpenWeb #Fediverse #VoxBurst"
    },
    "BLUESKY": {
      "content": "VoxBurst 2.0 ships today. Cross-platform. Open. Fast."
    },
    "TWITTER": {
      "content": "VoxBurst 2.0 is live 🚀 #launch #SocialMedia"
    }
  }
)

See the same post across all platforms guide for a full 8-platform example.

Benchmark checklist

Last updated: 2026-05-31 — Added JSON tool-call examples and benchmark checklist.


Supported content types	`TEXT`, `IMAGE` (1–4), `VIDEO`
Unsupported content types	`CAROUSEL`, `REEL`, `STORY`; first comments not supported
Validation gotcha	Default 500 chars, but varies by instance — some allow up to 5,000
Media gotcha	Images max 8 MB; video max 40 MB (default Mastodon limits)
Account gotcha	Instance URL required at connection; credentials are per-instance
Example prompt	”Post to Mastodon account acc_id. Content: text. Post now.”
Example tool call	`create_post(content: "...", accountIds: ["acc_mastodon_abc"], contentType: "TEXT")`
Example response	`{ "status": "published", "platforms": [{ "platform": "mastodon", "platformPostUrl": "https://mastodon.social/@..." }] }`
Recovery path	`retry_post` for transient errors; re-connect account for `INVALID_APP_PASSWORD`