mastodon
GitHub通过 Mastodon REST API 管理个人账号动态。支持发布、删除和查询状态（toots），展示互动数据，并可选上传媒体附件。需验证令牌权限，发布前确认可见性。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill mastodon -g -y
SKILL.md
Frontmatter
{
"name": "mastodon",
"license": "Apache-2.0",
"metadata": {
"author": "acedatacloud",
"version": "1.0"
},
"connections": [
"mastodon"
],
"description": "Publish, delete and read your own posts (toots) on any Mastodon instance via the Mastodon REST API. Use when the user wants to post a toot to their Mastodon \/ fediverse account, cross-post an article as a short dev-focused post, delete a toot, or list their own recent posts with engagement stats (boosts, favourites, replies).",
"when_to_use": "Trigger when the user wants to publish a status\/toot to their Mastodon\naccount, delete one, or review their own recent posts and engagement.\nMastodon is federated: the connector stores the instance base URL plus a\npersonal access token, so every call targets the user's own instance.\nConfirm visibility (public\/unlisted) before posting publicly.\n",
"allowed_tools": [
"Bash"
]
}
Call the Mastodon REST API with curl + jq. Two connector credentials are
injected: $MASTODON_BASE_URL (the instance, e.g. https://mastodon.social)
and $MASTODON_ACCESS_TOKEN. Every request sends the header
Authorization: Bearer $MASTODON_ACCESS_TOKEN.
Errors come back as JSON {"error":"<message>"} — show it verbatim. 401
("The access token is invalid") means the token is wrong/revoked → the user
must re-connect the Mastodon connector. Posting needs the token to have the
write (or write:statuses) scope.
Always confirm the token + account first (also gives the account id you
need to list your own toots):
curl -sS "$MASTODON_BASE_URL/api/v1/accounts/verify_credentials" \
-H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
| jq '{id, username, acct, display_name, followers: .followers_count, statuses: .statuses_count}'
Post a toot
Confirm with the user before posting publicly. Default visibility to
unlisted unless they say post publicly; use public only on request.
STATUS_TEXT="Hello fediverse 👋 #introductions"
curl -sS -X POST "$MASTODON_BASE_URL/api/v1/statuses" \
-H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
--data-urlencode "status=$STATUS_TEXT" \
--data-urlencode "visibility=unlisted" \
--data-urlencode "language=en" \
| jq '{id, url, visibility, created_at}'
visibilityis one ofpublic,unlisted,private,direct.- Optional params:
spoiler_text(content warning),in_reply_to_id(reply),sensitive=true,language(ISO 639-1). Idempotency-Key(any unique string;uuidgenhere) prevents duplicate posts if the request is retried within ~1h. Use--data-urlencodeso hashtags, emoji and newlines in the text are encoded correctly.- Default post length is 500 chars (instance-configurable); longer text →
422 {"error":"Validation failed: Text ..."}.
List my recent toots + engagement
Use the id from verify_credentials:
ACCT_ID="14715" # from verify_credentials
curl -sS "$MASTODON_BASE_URL/api/v1/accounts/$ACCT_ID/statuses?limit=20&exclude_replies=true&exclude_reblogs=true" \
-H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
| jq '.[] | {id, url, boosts: .reblogs_count, favs: .favourites_count, replies: .replies_count, created_at}'
limit max 40. Other filters: only_media, pinned, tagged=<hashtag>.
Delete a toot
curl -sS -X DELETE "$MASTODON_BASE_URL/api/v1/statuses/STATUS_ID" \
-H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" | jq '{id, deleted: true}'
Deleting returns the status with its source text so you can delete-and-redraft.
404 {"error":"Record not found"} = not yours or already gone.
Attaching media (optional)
Upload each image/video via POST $MASTODON_BASE_URL/api/v2/media
(multipart/form-data, field file) to get a media id, then pass the ids as
media_ids[] when posting the status. See the docs for the full media contract:
https://docs.joinmastodon.org/methods/media/
Gotchas
- Federated: the API only ever targets
$MASTODON_BASE_URL(the user's own instance). There is no global endpoint — a token from instance A won't work on instance B. - Scopes: reading needs
read(orread:accounts/read:statuses); posting/deleting needswrite(orwrite:statuses). A403("This action is outside the authorized scopes") means the token lacks a scope. - Rate limits: Mastodon rate-limits per token; space out bulk posts or you'll
get
429. verify_credentialsreturns HTML in fields likenote; the plaintext source lives under thesourceobject.
Version History
- e0220ca Current 2026-07-05 22:54
