How to post to Mastodon from Claude Code

Set it up and post, step by step

Prompt to copy once Mastodon is connected: Read CHANGELOG.md, write a Mastodon thread of 3 posts about v2.4 with CamelCase hashtags and the release link in a reply under the last one, show it to me, and schedule it for Thursday at 10am.

1. Add PostWire to Claude Code

   In your terminal run claude mcp add --transport http postwire https://postwire.io/api/mcp (add --scope user to have it in every project), then type /mcp in Claude Code and pick postwire to sign in. The sign-in asks for your email and a 6-digit code, which also creates a free PostWire account if you have none: no password and no card.

2. Or install the skill instead

   npx skills add https://postwire.io --skill schedule-posts adds PostWire's scheduling skill to Claude Code instead. It uses your key from the environment: copy it in the dashboard under API & MCP and set POSTWIRE_API_KEY. The skill is a plain file you can read first: schedule-posts/SKILL.md.

3. Create a Mastodon access token

   On your Mastodon server, open Preferences → Development → New application, name it "PostWire", tick only write:statuses and write:media, save, and copy Your access token. With those two scopes the token can post and upload media; it cannot read your timeline or your messages. Deleting the application in Mastodon disconnects PostWire.

4. Connect Mastodon

   Ask "connect my Mastodon". Claude Code calls create_connect_link and prints a one-hour link; choose Mastodon there and paste your server's address (https://mastodon.social, https://fosstodon.org or your own instance) and the token. Before saving, PostWire asks your server whether the token is valid, so a wrong token is refused on that page, and it reads the server's post length limit to measure your toots against it. The address has to be https and a public server.

5. Ask for the toot or the thread

   "Write a Mastodon post about the new CSV import." generate_posts returns a draft and publishes nothing: within 500 characters, community-first with no marketing-speak, and 2 to 4 hashtags in CamelCase (#OpenSource, which screen readers read out word by word). Ask for a thread, or give it an idea too long for one post, and it returns text (the first post) plus thread (the posts after it); a link comes back in first_comment, to go in a reply under the last post.

6. Post now, or schedule it

   Say "post it" and Claude Code calls post_to_social; say "schedule it for Thursday at 10am" and it calls schedule_post, up to 365 days ahead, or with run_at: "next_slot". thread holds up to 9 posts after the first, each a reply to the one before, and first_comment is one more reply under the last one. Images and videos go in media, each with its own alt. This is the call:

   {
     "name": "schedule_post",
     "arguments": {
       "platforms": ["mastodon"],
       "per_platform": { "mastodon": {
         "text": "v2.4 is out. Sync is twice as fast, and conflicts finally show you both versions. #OpenSource #SelfHosted",
         "thread": [
           "We stopped syncing on every keystroke. Saves now batch every 2 seconds, which is most of the speed-up.",
           "Conflicts get a side-by-side view instead of a silent overwrite. Pick a side, or merge by hand."
         ],
         "first_comment": "Release notes and upgrade steps: https://example.com/changelog/2-4"
       } },
       "media": [
         { "url": "https://postwire.io/m/…/conflict-view.png", "alt": "Two versions of a note side by side, with the changed lines highlighted" }
       ],
       "run_at": "2026-11-05T10:00:00-05:00"
     }
   }

7. Open the toot

   The result carries the post's link on your server and, for a thread, the link of every post in it. If your server refuses a later post of a thread, the earlier ones stay up and the result says which went out and which did not; each reply carries an idempotency key, so nothing is posted twice.

"What's scheduled on Mastodon?" calls list_scheduled_posts, and "cancel Thursday's thread" calls cancel_scheduled_post; the same queue is on the dashboard's Queue page. Without Claude Code, the same post is POST /api/post with {"platforms": ["mastodon"], "text": "…"} and your key. Prefer to set it up by hand first? Open the dashboard, connect Mastodon under Accounts and copy your key under API & MCP.