Skip to main content

Tools reference

This page lists every tool exposed by the Mixpost MCP server, grouped by area. For an overview of how to connect and authenticate, see the MCP Server overview.

Tools at a glance

ToolTypeWhat it does
list-workspacesReadList accessible workspaces — call this first
get-workspaceReadDetails and counts for one workspace
list-accountsReadList connected social accounts
get-accountReadFull details for one account
list-postsReadList and filter posts
get-postReadFull details for one post
create-postWriteCreate, and optionally schedule or publish, a post
update-postWriteChange a post's content, accounts or tags
update-post-versionWriteUpdate a single content version of a post
delete-post-versionDestructiveRemove an account's own content version
attach-tags-to-postWriteAdd tags, keeping existing ones
detach-tags-from-postWriteRemove tags from a post
duplicate-postWriteCopy a post as a new draft
schedule-postWriteSchedule for a time, or publish now
unschedule-postWriteClear the schedule and return the post to draft
add-post-to-queueWriteQueue at the next available slot
delete-postDestructiveTrash or permanently delete a post
restore-postWriteRestore a post from the trash
list-tagsReadList workspace tags
get-tagReadDetails for one tag
create-tagWriteCreate a tag
update-tagWriteUpdate a tag's name or colour
list-mediaReadList media library files
get-mediaReadFull metadata for one file
upload-media-by-urlWriteAdd a file to the library from a URL
get-media-upload-statusReadCheck a background upload's progress

Common parameters

Two arguments appear across most tools:

KeyFormatRequiredDescription
workspacestringrequiredUUID of the workspace to operate on. Obtain it from list-workspaces. Required by every tool except list-workspaces.
timezonestringoptionalIANA timezone (e.g. America/New_York) used to interpret input dates and format dates in the response. Defaults to your account timezone, then to UTC.

Write operations (create, update, schedule, delete, etc.) require the token owner to have the Member or Admin role in the workspace. See Roles and permissions.


Workspaces

list-workspaces

Read-only. List the workspaces the authenticated user can access, most recently updated first. Call this first — every other tool needs a workspace uuid.

Parameters: none.

Returns: count and a workspaces array of { uuid, name, role }.

get-workspace

Read-only. Get details about a single workspace: name, the user's role and approval rights, and the number of connected accounts, posts and members.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
timezonestringoptionalTimezone for returned datetimes.

Returns: a workspace object — { uuid, name, created_at, role, can_approve, accounts_count, posts_count, users_count }.


Accounts

list-accounts

Read-only. List the social media accounts connected to a workspace. Returns each account's numeric id (used with create-post), name, username, provider and authorization status.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
providerstringoptionalFilter by provider identifier, e.g. twitter, facebook_page, linkedin.
authorized_onlybooleanoptionalWhen true, return only accounts whose authorization is still valid.

Returns: count and an accounts array of { id, name, username, provider, authorized }.

get-account

Read-only. Get full details for a single connected account by its numeric id, including profile image, external profile URL and provider-specific data (e.g. follower metrics).

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
account_idintegerrequiredNumeric id of the account. Obtain it from list-accounts.
timezonestringoptionalTimezone for returned datetimes.

Returns: an account object — { id, uuid, name, suffix, username, provider, provider_name, authorized, image, external_url, data, created_at }.


Posts

list-posts

Read-only. List posts in a workspace, most recent first, with optional filters. Returns a compact summary per post: uuid, status, schedule/publish/created times, accounts, tags, plain-text content and media count.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
statusstringoptionalOne of draft, scheduled, published, failed, needs_approval, trash.
account_idsarray<integer>optionalOnly posts assigned to any of these account ids.
tag_idsarray<integer>optionalOnly posts tagged with any of these tag ids.
keywordstringoptionalOnly posts whose content contains this text.
scheduled_fromstringoptionalOnly posts scheduled at or after this UTC date/time. Format Y-m-d or Y-m-d H:i.
scheduled_tostringoptionalOnly posts scheduled at or before this UTC date/time. A date-only value includes the whole day.
created_fromstringoptionalOnly posts created at or after this UTC date/time.
created_tostringoptionalOnly posts created at or before this UTC date/time.
limitintegeroptionalMaximum number of posts to return (1–100). Defaults to 25.
timezonestringoptionalTimezone for returned datetimes.

Returns: count and a posts array of post summaries (see Post summary shape).

get-post

Read-only. Get the details of a single post by its uuid: status, schedule/publish times, author, tags, the accounts it targets (with live post URLs and any publish errors) and every content version with the text and the media ids of each item.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
includearray<string>optionalExtra parts of each content version to return (see below). Omitted by default.
timezonestringoptionalTimezone for returned datetimes.

Returns: a post object with author, tags, per-account publish info (external_url, errors) and the versions array. Each version carries synced_with: 0 or an account id when it follows that version (and holds a copy of its content), null when its content is its own.

Asking for more with include

Everything a version carries beyond its text costs real tokens, and most calls need none of it — so it is left out unless you name it. By default each content item returns body plus media as plain media ids, which is exactly what the write tools take back.

ValueAdds
mediaExpands each media id into { id, name, type, url, alt_text }.
optionsThe per-provider options object of each version (see Versions).
content_urlsThe url attached to each content item.
video_thumbsThe thumbnail chosen for each video: { media_id, thumb_id, thumb_url }.
allAll of the above. Ask for this only when you genuinely need everything.
{
"workspace": "6059e1b3-e102-4be5-951b-82698abd9ee3",
"uuid": "0f5b1c7a-2f4d-4d2e-9e2a-6f3f2d1c8b90",
"include": ["media", "options"]
}

create-post

Writes data. Create a post and optionally schedule or publish it. Provide simple content for a single-version post, or versions for per-account content.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
account_idsarray<integer>requiredNumeric IDs of the connected accounts to post to (at least one). Obtain them from list-accounts.
contentstringoptionalThe text body, used as the default for every account. Required unless versions is given.
schedulestringoptionaldraft (default), now (publish immediately), scheduled (publish at scheduled_at), or queue (next slot).
scheduled_atstringoptionalWhen to publish, format Y-m-d H:i (e.g. 2026-05-22 14:30). Required when schedule is scheduled.
tagsarray<integer>optionalNumeric tag IDs to attach. Obtain them from list-tags.
versionsarrayoptionalPer-account content versions (see Versions).
timezonestringoptionalTimezone for scheduled_at and returned datetimes.

Returns: a message, the created post summary, and the timezone used.

A post created to be published now, scheduled or queued must meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and creates nothing. A draft is not checked.

update-post

Writes data. Update an existing post's content (content or versions), target accounts and/or tags. Only the fields you provide change, and the schedule is left untouched — use schedule-post for timing, or unschedule-post to clear it. The post must not already be published, failed or publishing.

Each part is saved through the same endpoint the editor uses, so a post an agent updates goes through the same validation, per-provider option handling and events as one updated in the dashboard.

A scheduled post must still meet the publishing requirements of its accounts' platforms once the change is applied — the new content checked against the new accounts, when both change. Otherwise the tool returns an error listing what to fix and changes nothing; fix it in the same call, or unschedule-post first. A draft is not checked.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
contentstringoptionalNew text body. Replaces the body of the post's original content.
account_idsarray<integer>optionalReplace the targeted accounts with these account ids (at least one).
tagsarray<integer>optionalReplace the post's tags. Pass an empty array to remove all tags.
versionsarrayoptionalVersions to create or update (see Versions). Versions you leave out keep what they had — remove one with delete-post-version.
timezonestringoptionalTimezone for returned datetimes.

Returns: a message, the updated post summary, and the timezone used.

update-post-version

Writes data. Update a single content version of a post, leaving the others untouched. Target the original/default version with account_id 0, or an account id to update (or create) that account's version. To replace every version at once, use update-post.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
account_idintegerrequired0 for the original/default version, or a connected account id for that account's version.
contentarrayrequiredOrdered content items for this version (at least one); more than one publishes a thread.
optionsobjectoptionalPer-provider post options, keyed by provider identifier (e.g. { "mastodon": { … } }).
timezonestringoptionalTimezone for returned datetimes.

Each item in content has body (string), media (array of media ids) and url (string), all optional. Leave media out to keep the media the item already has; pass an empty array to clear it. Video thumbnails are always preserved — they are not part of the tool's input.

options are validated against the target provider's rules and normalised the way the dashboard normalises them; options for an unknown provider are dropped. Leave options out to keep the ones the version already has.

On a scheduled post, the version must leave the post meeting the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and changes nothing.

A version that follows another (its synced_with in get-post is not null) stops following it once this tool writes its content.

Returns: a message, the updated post summary, and the timezone used.

delete-post-version

Destructive. Remove an account's own content version from a post, so that account falls back to the post's default content. The default version itself has no account and cannot be removed this way. The post must not already be published, failed or publishing.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
account_idintegerrequiredThe connected account whose own version is removed. Obtain it from list-accounts.

Use get-post to see which accounts have a version of their own — each entry in versions carries the account_id it belongs to.

On a scheduled post, the default content the account falls back to must meet the publishing requirements of that account's platform; otherwise the tool returns an error listing what to fix and removes nothing.

Returns: a message, the post uuid and the account_id that was reverted. The post itself is not returned — the only version a post summary carries is the default one, which this call leaves alone.

attach-tags-to-post

Writes data. Attach one or more tags to a post, keeping any tags it already has. To replace a post's tags instead, use update-post.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
tag_idsarray<integer>requiredTag ids to attach (at least one), kept in addition to existing tags.
timezonestringoptionalTimezone for returned datetimes.

Returns: a message and the updated post summary.

detach-tags-from-post

Writes data. Remove one or more tags from a post, leaving its other tags in place.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
tag_idsarray<integer>requiredTag ids to remove (at least one).
timezonestringoptionalTimezone for returned datetimes.

Returns: a message and the updated post summary.

duplicate-post

Writes data. Duplicate an existing post. Creates a new draft copy with the same accounts, tags and content versions; the copy is never scheduled or published.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post to duplicate.
timezonestringoptionalTimezone for returned datetimes.

Returns: a message and the new draft post summary.

schedule-post

Writes data. Schedule an existing post for a specific date/time, or publish it immediately with post_now. The post must have at least one account, a future scheduled time, content the platform of every account can publish, and must not already be published, failed or publishing.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
scheduled_atstringoptionalWhen to publish, format Y-m-d H:i. Required unless post_now is true or the post already has a scheduled time.
post_nowbooleanoptionalWhen true, publish immediately instead of scheduling.
timezonestringoptionalTimezone for scheduled_at and returned datetimes.

Returns: a message and the updated post summary. If the workspace requires approval, the post becomes needs_approval; otherwise it is queued for publishing.

The post must also meet the publishing requirements of its accounts' platforms — media for an Instagram post, a board for Pinterest, a title for YouTube. Otherwise the tool returns an error listing what to fix, and the post stays as it was.

unschedule-post

Writes data. Clear a post's scheduled time and take it back to draft, so it stays put until it is scheduled again. Its accounts, tags and content are untouched. Works on a scheduled post, one waiting in the queue and one awaiting approval; a post that has already been published or failed, or one being published right now, cannot be unscheduled.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.

Returns: a message and the post uuid. The post itself is not returned — nothing but the schedule changed.

Use schedule-post to put it back on the calendar, or add-post-to-queue to send it to the next free slot.

add-post-to-queue

Writes data. Add an existing post to the posting queue — it is scheduled at the next available slot of the workspace's posting schedule. The post must have at least one account, content the platform of every account can publish, and must not already be published, failed or publishing.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
timezonestringoptionalTimezone for returned datetimes.

Returns: a message and the updated post summary. The workspace must have posting schedule times configured.

The post must also meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix, and the post stays as it was.

delete-post

Destructive. Delete a post. By default it is moved to the trash and can be restored; set permanent to true to delete it irreversibly. Use delete_mode to also remove the published post from the connected social platforms.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the post. Obtain it from list-posts.
delete_modestringoptionalapp_only (default), social_only, or app_and_social.
permanentbooleanoptionalWhen true, permanently delete instead of moving to trash. Only applies when removing from Mixpost. Defaults to false.

Returns: a message and the deleted post's uuid.

restore-post

Writes data. Restore a post from the trash. The post is recovered as a draft. Only posts moved to the trash (not permanently deleted) can be restored. Find them with list-posts using status: "trash".

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the trashed post.
timezonestringoptionalTimezone for returned datetimes.

Returns: a message and the restored post summary.


Tags

list-tags

Read-only. List the tags defined in a workspace.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.

Returns: count and a tags array of { id, name, hex_color }.

get-tag

Read-only. Get details for a single tag by its numeric id.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
tag_idintegerrequiredNumeric id of the tag. From list-tags.

Returns: a tag object — { id, name, hex_color }.

create-tag

Writes data. Create a tag in a workspace.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
namestringrequiredThe tag name (max 255 characters).
hex_colorstringrequiredThe tag colour as a hex code, e.g. #1d9bf0.

Returns: a message and the created tag.

update-tag

Writes data. Update a tag's name and/or colour. Only the fields you provide change.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
tag_idintegerrequiredNumeric id of the tag. From list-tags.
namestringoptionalNew tag name (max 255 characters).
hex_colorstringoptionalNew tag colour as a hex code, e.g. #1d9bf0.

Returns: a message and the updated tag.


Media

list-media

Read-only. List the media files (images, GIFs and videos) in a workspace's library, newest first. Returns each file's numeric id (which can be attached to a post version), name, type and URL.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
typestringoptionalFilter by image, gif, or video.
limitintegeroptionalMaximum number of files to return (1–100). Defaults to 50.
timezonestringoptionalTimezone for returned datetimes.

Returns: count and a media array of summaries — { id, uuid, name, type, mime_type, url, alt_text, created_at }.

get-media

Read-only. Get the full metadata for a single media file by its uuid.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
uuidstringrequiredUUID of the media file. From list-media.
timezonestringoptionalTimezone for returned datetimes.

Returns: a media object — { id, uuid, name, type, mime_type, url, thumb_url, alt_text, source, … }.

upload-media-by-url

Writes data. Upload a media file to the library by downloading it from a public URL. Small files are downloaded immediately and returned; large files download in the background and appear in list-media once complete.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
urlstringrequiredPublicly accessible URL of the media file to download.
alt_textstringoptionalAlternative text describing the media (max 255 characters).
timezonestringoptionalTimezone for returned datetimes.

Returns: for a small file, a message and the uploaded media. For a large file, a message, status: "pending" and a download_id — poll it with get-media-upload-status.

get-media-upload-status

Read-only. Check the progress of a background media download started by upload-media-by-url.

KeyFormatRequiredDescription
workspacestringrequiredWorkspace UUID.
download_idstringrequiredThe download_id returned by upload-media-by-url for a large file.
timezonestringoptionalTimezone for returned datetimes.

Returns: while in progress, a status (pending, downloading, processing) and a progress percentage; on completion, status: "completed" and the uploaded media; on failure, an error message.


Provider identifiers

The provider value on an account — and the provider filter on list-accounts — uses these identifiers:

IdentifierPlatform
twitterX (Twitter)
facebook_pageFacebook Page
instagramInstagram (via a Facebook Page)
instagram_standaloneInstagram (standalone)
threadsThreads
linkedinLinkedIn (profile)
linkedin_pageLinkedIn Page
tiktokTikTok
pinterestPinterest
youtubeYouTube
gbpGoogle Business Profile
mastodonMastodon
blueskyBluesky
pixelfedPixelfed

Versions

The create-post, update-post and update-post-version tools support per-account content versions, so a single post can have different text or media for each network. The structure mirrors the REST API's post versions:

{
"versions": [
{
"account_id": 0,
"content": [
{
"body": "This is the default content used for every account.",
"media": [1],
"url": null
}
],
"options": {
"mastodon": { "sensitive": false }
}
},
{
"account_id": 12,
"content": [
{ "body": "A custom version just for this account." }
]
}
]
}
KeyFormatRequiredDescription
versions.*.account_idintegerrequiredThe account this version targets. Use 0 for the original/default version.
versions.*.contentarrayrequiredOrdered content items. Provide more than one to publish a thread.
versions.*.content.*.bodystringoptionalThe text body of this content item.
versions.*.content.*.mediaarray<integer>optionalMedia IDs to attach. Obtain them from list-media or upload-media-by-url.
versions.*.content.*.urlstringoptionalA URL associated with the content (supported by Facebook and LinkedIn).
versions.*.optionsobjectoptional

Options available for each social service provider.

Only keys matching a registered provider are kept — unknown keys are silently dropped, and rules are applied only for the provider keys you actually send.

{
"facebook_page": {
"type": "post" // post,reel,story
},
"instagram": {
"type": "post" // post,reel,story
},
"instagram_standalone": {
"type": "post" // post,reel,story | Same options as `instagram`
},
"linkedin": {
"visibility": "PUBLIC" // PUBLIC,CONNECTIONS | Required when the `linkedin` object is present
},
"linkedin_page": {
"visibility": "PUBLIC" // PUBLIC,CONNECTIONS | Same options as `linkedin`
},
"mastodon": {
"sensitive": false // boolean | Marks the post's media as sensitive
},
"pixelfed": {
"type": "post", // post,story
"sensitive": false, // boolean
"duration": 10, // integer | Story duration in seconds (1-30). Only applies if type is `story`
"can_reply": true, // boolean
"can_react": true // boolean
},
"pinterest": {
"link": null, // null|string
"title": "", // string
"boards": {
"account-1": "971672010430333260" // string | The key `account-*` is the ID of your Pinterest account
}
},
"youtube": {
"title": null, // null|string
"status": "public", // public,private,unlisted
"made_for_kids": false // boolean
},
"gbp": {
// Google Business Profile
"type": "post", // post,offer,event
"button": "NONE", // NONE,BOOK,ORDER,SHOP,LEARN_MORE,SIGN_UP,CALL
"button_link": "", // string | Leave empty if button is `NONE` or `CALL`
"offer_has_details": false, // boolean | Only applies if type is `offer`
"coupon_code": "", // string | Only applies if type is `offer` and `offer_has_details` is true
"offer_link": "", // string | Only applies if type is `offer` and `offer_has_details` is true
"terms": "", // string | Only applies if type is `offer` and `offer_has_details` is true
"event_title": "", // string | Only applies if type is `event` or `offer`
"start_date": null, // null|string | Only applies if type is `event` or `offer`
"end_date": null, // null|string | Only applies if type is `event` or `offer`
"event_has_time": false, // boolean | Only applies if type is `event`
"start_time": "09:00", // string | Only applies if type is `event` and `event_has_time` is true
"end_time": "17:00" // string | Only applies if type is `event` and `event_has_time` is true
},
"tiktok": {
// For every `tiktok` option, the key `account-*` is the ID of your TikTok account
"privacy_level": {
"account-2": "PUBLIC_TO_EVERYONE" // string | PUBLIC_TO_EVERYONE,MUTUAL_FOLLOW_FRIENDS,FOLLOWER_OF_CREATOR,SELF_ONLY
},
"allow_comments": {
"account-2": true // boolean
},
"allow_duet": {
"account-2": false // boolean
},
"allow_stitch": {
"account-2": false // boolean
},
"is_aigc": {
"account-2": false // boolean | Flags the content as AI-generated
},
"auto_add_music": {
"account-2": false // boolean
},
"content_disclosure": {
"account-2": false // boolean
},
"brand_organic_toggle": {
"account-2": false // boolean
},
"brand_content_toggle": {
"account-2": false // boolean
}
}
}

twitter, threads and bluesky are registered providers but define no options — send {} (or omit them). In responses, the options object always contains a key for every registered provider, so these appear as {} even when you didn't send them.

Every post needs a default version

The version with account_id 0 is the default content, applied to every account that does not have its own account-specific version.

  • With create-post, exactly one version must have account_id 0 — the post has no content yet.
  • With update-post, the versions you send are created or updated and the rest are left alone, so 0 only has to be included if the post does not already have a default version.
Updating does not wipe what you leave out

A content item you send replaces the stored one, but the keys you omit are carried over from it: leave media or url out and the item keeps them, and video thumbnails are always preserved since they are not part of the tools' input. Pass an empty media array to actually clear the media.

Removing an account's version is a separate call — delete-post-version — never something that happens because you left it out of versions.


Post summary shape

Most post tools return a compact summary optimised for agents (the heavy web payload is omitted to save tokens):

{
"uuid": "6059e1b3-e102-4be5-951b-82698abd9ee3",
"status": "scheduled",
"scheduled_at": "2026-07-01 09:00:00",
"published_at": null,
"created_at": "2026-06-25 14:12:03",
"accounts": [
{ "id": 12, "name": "Acme", "username": "acme", "provider": "twitter", "authorized": true }
],
"tags": [
{ "id": 3, "name": "Launch" }
],
"content": "We just shipped a big update 🚀",
"media_count": 1
}

status is one of draft, scheduled, published, failed, needs_approval, publishing or trash. content is the plain text of the post's original version, with multiple content items joined by blank lines.